From bacb5e68c6137247b550213e0d265f55def06de4 Mon Sep 17 00:00:00 2001 From: santiago fraire Date: 2019年4月14日 22:03:39 +0200 Subject: [PATCH] docs: mkdocs documentation --- README.rst | 167 +++++------------------------------------- docs/bump.md | 124 +++++++++++++++++++++++++++++++ docs/config.md | 39 ++++++++++ docs/customization.md | 85 +++++++++++++++++++++ docs/index.md | 112 ++++++++++++++++++++++++++++ mkdocs.yml | 22 ++++++ pyproject.toml | 2 + 7 files changed, 403 insertions(+), 148 deletions(-) create mode 100644 docs/bump.md create mode 100644 docs/config.md create mode 100644 docs/customization.md create mode 100644 docs/index.md create mode 100644 mkdocs.yml diff --git a/README.rst b/README.rst index 3782ab6e3e..c113b599c4 100644 --- a/README.rst +++ b/README.rst @@ -35,14 +35,17 @@ Commitizen About ========== -Interactive tool to commit based on established rules (like conventional commits). +Commitizen is a tool designed for teams. -It comes with some defaults commit styles, -like conventional commits and jira and it's easily extendable. +Its main purpose is to define a standard way of commiting rules +and communicating it (using the cli provided by commitizen). -It's useful for teams, because it is possible to standardize the commiting style. +The reasoning behind it is that is easier to read, and enforces writing +descriptive commits. -Also includes an automatic version bump system based on semver. +Besides that, having a convetion on your commits, makes it possible to +parse them and use them for something else, like generating automatically +the version or a changelog. Installation @@ -66,11 +69,10 @@ Installation Features ======== -- Prompt your commit rules to the user -- Display information about your commit rules (schema, example, info) -- Auto **bump** version based on semver using your rules (currently there is only support for conventionalcommits) -- Future: New documentation -- Future: Autochangelog +- Command line utility to create commits with your rules. Defaults: `Conventional commits `_ +- Display information about your commit rules (commands: schema, example, info) +- Bump version automatically using semantic verisoning based on the commits. `Read More <./docs/bump.md>`_ +- Generate a changelog using "Keep a changelog" (Planned feature) Commit rules @@ -84,7 +86,6 @@ This is an example of how the git messages history would look like: :: - BREAKING CHANGE: command send has been removed fix: minor typos in code feat: new command update docs: improved commitizens tab in readme @@ -95,6 +96,12 @@ This is an example of how the git messages history would look like: docs(README): added about, installation, creating, etc feat(config): new loads from ~/.cz and working project .cz .cz.cfg and setup.cfg +And then using ``cz bump`` you can change the version of your project + +``feat`` to ``MINOR`` +``fix`` to ``PATCH`` + + Commitizens =========== @@ -155,142 +162,6 @@ Usage schema show commit schema bump bump semantic version based on the git log - -Configuration -============== - -**New!**: Support for ``pyproject.toml`` - -In your ``pyproject.toml`` you can add an entry like this: - -:: - - [tool.commitizen] - name = cz_conventional_commits - version = "0.1.0" - files = [ - "src/__version__.py", - "pyproject.toml" - ] - - -Also, you can create in your project folder a file called -:code:`.cz`, :code:`.cz.cfg` or in your :code:`setup.cfg` -or if you want to configure the global default in your user's home -folder a :code:`.cz` file with the following information: - -:: - - [commitizen] - name = cz_conventional_commits - version = 0.1.0 - files = [ - "src/__version__.py", - "pyproject.toml" - ] - -The extra tab at the end (``]``) is required. - -Creating a commiter -======================== - -Create a file starting with :code:`cz_` for example :code:`cz_jira.py`. -This prefix is used to detect the plugin. Same method `flask uses `_ - -Inherit from :code:`BaseCommitizen` and you must define :code:`questions` -and :code:`message`. The others are optionals. - - -.. code-block:: python - - from commitizen import BaseCommitizen - - class JiraCz(BaseCommitizen): - - def questions(self): - """Questions regarding the commit message. - - :rtype: list - """ - questions = [ - { - 'type': 'input', - 'name': 'title', - 'message': 'Commit title' - }, - { - 'type': 'input', - 'name': 'issue', - 'message': 'Jira Issue number:' - }, - ] - return questions - - def message(self, answers): - """Generate the message with the given answers. - - :type answers: dict - :rtype: string - """ - return '{0} (#{1})'.format(answers['title'], answers['issue']) - - def example(self): - """Provide an example to help understand the style (OPTIONAL) - Used by cz example. - - :rtype: string - """ - return 'Problem with user (#321)' - - def schema(self): - """Show the schema used (OPTIONAL) - - :rtype: string - """ - return ' (<issue>)' - - def info(self): - """Explanation of the commit rules. (OPTIONAL) - :rtype: string - """ - return 'We use this because is useful' - - - discover_this = JiraCz # used by the plugin system - - -The next file required is :code:`setup.py` modified from flask version - -.. code-block:: python - - from distutils.core import setup - - setup( - name='JiraCommitizen', - version='0.1.0', - py_modules=['cz_jira'], - license='MIT', - long_description='this is a long description', - install_requires=['commitizen'] - ) - -So at the end we would have - -:: - - . - ├── cz_jira.py - └── setup.py - -And that's it, you can install it without uploading to pypi by simply doing -:code:`pip install .` If you feel like it should be part of the repo, create a -PR. - -Python 2 support -================= - -There's no longer support for python 2. Nor planned suppport. - Contributing ============ @@ -299,4 +170,4 @@ Feel free to create a PR. 1. Clone the repo. 2. Add your modifications 3. Create a virtualenv -4. Run :code:`pytest -s --cov-report term-missing --cov=commitizen tests/` +4. Run :code:`./scripts/test` diff --git a/docs/bump.md b/docs/bump.md new file mode 100644 index 0000000000..dcd3275069 --- /dev/null +++ b/docs/bump.md @@ -0,0 +1,124 @@ +## About + +The version is bumped **automatically** based on the commits. + +The commits should follow the rules of the commiter in order to be parsed properly. + +It is possible to specify a **prerelease** (alpha, beta, release candidate) version. + +The version can also be **manually** bumped. + +The version format follows [semantic versioning][semver]. + +This means `MAJOR.MiNOR.PATCH` + +| Increment | Description | Conventional commit map | +| ------- | ----- | ------ | +| `MAJOR` | Breaking changes introduced | `BREAKING CHANGE` | +| `MINOR` | New features | `feat` | +| `PATCH` | Fixes | `fix` + everything else | + + +Prereleases are supported following python's [PEP 0440][pep440] + +The scheme of this format is + +``` +[N!]N(.N)*[{a|b|rc}N][.postN][.devN] +``` + +Some examples: + +``` +0.9.0 +0.9.1 +0.9.2 +0.9.10 +0.9.11 +1.0.0a0 # alpha +1.0.0a1 +1.0.0b0 # beta +1.0.0rc0 # release candidate +1.0.0rc1 +1.0.0 +1.0.1 +1.1.0 +2.0.0 +2.0.1a +``` + +`post` and `dev` releases are not supported yet. + +## Usage + +```bash +$ cz bump --help +usage: cz bump [-h] [--dry-run] [--tag-format TAG_FORMAT] + [--prerelease {alpha,beta,rc}] + [--increment {MAJOR,MINOR,PATCH}] + +optional arguments: + -h, --help show this help message and exit + --dry-run show output to stdout, no commit, no modified files + --tag-format TAG_FORMAT + format used to tag the commmit and read it, use it in + existing projects, wrap around simple quotes. + --prerelease {alpha,beta,rc}, -pr {alpha,beta,rc} + choose type of prerelease + --increment {MAJOR,MINOR,PATCH} + manually specify the desired increment +``` + + +## Configuration + +`tag_format` + +Used to read the format from the git tags, and also to generate the tags. + +Supports 2 types of formats, a simple and a more complex. + +```bash +cz bump --tag_format="v$version" +``` + +```bash +cz bump --tag_format="v$minor.$major.$path$prerelease" +``` + +In your `pyproject.toml` + +```toml +[commitizen] +tag_format = "v$minor.$major.$path$prerelease" +``` + +The variables must be preceded by a `$` sign. + +Suppported variables: + +| Variable | Description | +| --- | ----------- | +| `$version` | full generated version | +| `$major` | MAJOR increment | +| `$minor` | MINOR increment | +| `$patch` | PATCH increment | +| `$prerelease` | Prerelase (alpha, beta, release candidate) | + +`files` + +Used to identify the files which should be updated with the new version. +In your `pyproject.toml` + +Commitizen will update it's configuration (`pyproject.toml`, `.cz`) when bumping. + +```toml +[commitizen] +files = [ + "src/__version__.py", + "setup.py" +] +``` + +[pep440]: https://www.python.org/dev/peps/pep-0440/ +[semver]: https://semver.org/ \ No newline at end of file diff --git a/docs/config.md b/docs/config.md new file mode 100644 index 0000000000..3f06841948 --- /dev/null +++ b/docs/config.md @@ -0,0 +1,39 @@ +# Configuration + +**New!**: Support for `pyproject.toml` + +Add an entry to `pyproject.toml`. + + + [tool.commitizen] + name = "cz_conventional_commits" + version = "0.1.0" + files = [ + "src/__version__.py", + "pyproject.toml" + ] + + +Also, you can create in your project folder a file called `.cz`, +`.cz.cfg` or in your `setup.cfg` or if you want to configure the global +default in your user's home folder a `.cz` file with the following +information: + + [commitizen] + name = cz_conventional_commits + version = 0.1.0 + files = [ + "src/__version__.py", + "pyproject.toml" + ] + +The extra tab at the end (`]`) is required. + +## settings + +| Variable | Type | Default | Description | +| -------- | ---- | ------- | ----------- | +| name | str | `"cz_conventional_commits"` | Name of the commiting rules to use | +| version | str | `None` | Current version. Example: "0.1.2" | +| files | list | `[ ]` | Files were the version needs to be updated | +| tag_format | str | `None` | Format for the git tag, useful for old projects, that use a convention like `"v1.2.1"`. [See more](/bump#configuration) | diff --git a/docs/customization.md b/docs/customization.md new file mode 100644 index 0000000000..13da74b703 --- /dev/null +++ b/docs/customization.md @@ -0,0 +1,85 @@ +## Custom commit rules + +Create a file starting with `cz_` for example `cz_jira.py`. This prefix +is used to detect the plugin. Same method [flask uses] + +Inherit from `BaseCommitizen` and you must define `questions` and +`message`. The others are optionals. + +```python +from commitizen.cz.base import BaseCommitizen + +class JiraCz(BaseCommitizen): + + def questions(self) -> list: + """Questions regarding the commit message.""" + questions = [ + { + 'type': 'input', + 'name': 'title', + 'message': 'Commit title' + }, + { + 'type': 'input', + 'name': 'issue', + 'message': 'Jira Issue number:' + }, + ] + return questions + + def message(self, answers: dict) -> str: + """Generate the message with the given answers.""" + return '{0} (#{1})'.format(answers['title'], answers['issue']) + + def example(self) -> str: + """Provide an example to help understand the style (OPTIONAL) + + Used by `cz example`. + """ + return 'Problem with user (#321)' + + def schema(self) -> str: + """Show the schema used (OPTIONAL) + + Used by `cz schema`. + """ + return '<title> (<issue>)' + + def info(self) -> str: + """Explanation of the commit rules. (OPTIONAL) + + Used by `cz info`. + """ + return 'We use this because is useful' + + +discover_this = JiraCz # used by the plugin system +``` + +The next file required is `setup.py` modified from flask version + +```python +from setuptools import setup + +setup( + name='JiraCommitizen', + version='0.1.0', + py_modules=['cz_jira'], + license='MIT', + long_description='this is a long description', + install_requires=['commitizen'] +) +``` + +So at the end we would have + + . + ├── cz_jira.py + └── setup.py + +And that's it, you can install it without uploading to pypi by simply +doing `pip install .` + +If you feel like it should be part of this repo, create a PR. + +[flask uses]: http://flask.pocoo.org/docs/0.12/extensiondev/ diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000000..1812d15b0c --- /dev/null +++ b/docs/index.md @@ -0,0 +1,112 @@ + +[![Travis](https://img.shields.io/travis/Woile/commitizen.svg?style=flat-square)](https://travis-ci.org/Woile/commitizen) +[![Conventional +Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg?style=flat-square)](https://conventionalcommits.org) +[![PyPI Package latest +release](https://img.shields.io/pypi/v/commitizen.svg?style=flat-square)](https://pypi.org/project/commitizen/) +[![Supported +versions](https://img.shields.io/pypi/pyversions/commitizen.svg?style=flat-square)](https://pypi.org/project/commitizen/) +[![Codecov](https://img.shields.io/codecov/c/github/Woile/commitizen.svg?style=flat-square)](https://codecov.io/gh/Woile/commitizen) + + +![Using commitizen cli](images/demo.gif) + +## About + +Commitizen is a tool designed for teams. + +Its main purpose is to define a standard way of commiting rules +and communicating it (using the cli provided by commitizen). + +The reasoning behind it is that is easier to read, and enforces writing +descriptive commits. + +Besides that, having a convetion on your commits, makes it possible to +parse them and use them for something else, like generating automatically +the version or a changelog. + +### Commitizen features + +* Command line utility to create commits with your rules. Defaults: [Conventional commits][conventional_commits] +* Display information about your commit rules (commands: schema, example, info) +* Bump version automatically using [semantic verisoning][semver] based on the commits. [Read More](./bump.md) +* Generate a changelog using [Keep a changelog][keepchangelog] (Planned feature) + +## Requirements + +Python 3.6+ + +[Git][gitscm] + +## Installation + +Global installation + +```bash +sudo pip3 install -U Commitizen +``` + +### Python project + +You can add it to your local project using one of these: +```bash +pip install -U commitizen +``` + +```bash +poetry add commitizen --dev +``` + +## Usage + +### Commiting + + +Run in your terminal + + cz commit + +or the shortcut + + cz c + +### Help + +```bash +$ cz --help +usage: cz [-h] [--debug] [-n NAME] [--version] + {ls,commit,c,example,info,schema,bump} ... + +Commitizen is a cli tool to generate conventional commits. +For more information about the topic go to https://conventionalcommits.org/ + +optional arguments: +-h, --help show this help message and exit +--debug use debug mode +-n NAME, --name NAME use the given commitizen +--version get the version of the installed commitizen + +commands: +{ls,commit,c,example,info,schema,bump} + ls show available commitizens + commit (c) create new commit + example show commit example + info show information about the cz + schema show commit schema + bump bump semantic version based on the git log +``` + +## Contributing + +Feel free to create a PR. + +1. Clone the repo. +2. Add your modifications +3. Create a virtualenv +4. Run `./scripts/test` + +[conventional_commits]: https://www.conventionalcommits.org +[semver]: https://semver.org/ +[keepchangelog]: https://keepachangelog.com/ +[gitscm]: https://git-scm.com/downloads +[Travis]: https://img.shields.io/travis/Woile/commitizen.svg?style=flat-square diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000000..699e06b196 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,22 @@ +site_name: Commitizen +site_description: commit rules, semantic version, conventional commits + +theme: + name: 'material' + +repo_name: Woile/commitizen +repo_url: https://github.com/Woile/commitizen +edit_uri: "" + +nav: + - Introduction: 'index.md' + - Configuration: 'config.md' + - Bump: 'bump.md' + - Customization: 'customization.md' + +markdown_extensions: + - markdown.extensions.codehilite: + guess_lang: false + - admonition + - codehilite + - extra \ No newline at end of file diff --git a/pyproject.toml b/pyproject.toml index f0d699cf41..0619b5bad1 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -61,6 +61,8 @@ pytest-cov = "^2.6" pytest-mock = "^1.10" codecov = "^2.0" mypy = "^0.700.0" +mkdocs = "^1.0" +mkdocs-material = "^4.1" [tool.poetry.scripts] cz = "commitizen.cli:main" </div><div class="naked_ctrl"> <form action="/index.cgi/contrast" method="get" name="gate"> <p><a href="http://altstyle.alfasado.net">AltStyle</a> によって変換されたページ <a href="https://patch-diff.githubusercontent.com/raw/commitizen-tools/commitizen/pull/15.patch">(->オリジナル)</a> / <label>アドレス: <input type="text" name="naked_post_url" value="https://patch-diff.githubusercontent.com/raw/commitizen-tools/commitizen/pull/15.patch" size="22" /></label> <label>モード: <select name="naked_post_mode"> <option value="default">デフォルト</option> <option value="speech">音声ブラウザ</option> <option value="ruby">ルビ付き</option> <option value="contrast" selected="selected">配色反転</option> <option value="larger-text">文字拡大</option> <option value="mobile">モバイル</option> </select> <input type="submit" value="表示" /> </p> </form> </div>