Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

Commit bacb5e6

Browse files
committed
docs: mkdocs documentation
1 parent 17efb44 commit bacb5e6

File tree

7 files changed

+403
-148
lines changed

7 files changed

+403
-148
lines changed

‎README.rst‎

Lines changed: 19 additions & 148 deletions
Original file line numberDiff line numberDiff line change
@@ -35,14 +35,17 @@ Commitizen
3535
About
3636
==========
3737

38-
Interactive tool to commit based on established rules (like conventional commits).
38+
Commitizen is a tool designed for teams.
3939

40-
It comes with some defaults commit styles,
41-
like conventional commits and jira and it's easily extendable.
40+
Its main purpose is to define a standard way of commiting rules
41+
and communicating it (using the cli provided by commitizen).
4242

43-
It's useful for teams, because it is possible to standardize the commiting style.
43+
The reasoning behind it is that is easier to read, and enforces writing
44+
descriptive commits.
4445

45-
Also includes an automatic version bump system based on semver.
46+
Besides that, having a convetion on your commits, makes it possible to
47+
parse them and use them for something else, like generating automatically
48+
the version or a changelog.
4649

4750

4851
Installation
@@ -66,11 +69,10 @@ Installation
6669
Features
6770
========
6871

69-
- Prompt your commit rules to the user
70-
- Display information about your commit rules (schema, example, info)
71-
- Auto **bump** version based on semver using your rules (currently there is only support for conventionalcommits)
72-
- Future: New documentation
73-
- Future: Autochangelog
72+
- Command line utility to create commits with your rules. Defaults: `Conventional commits <https://www.conventionalcommits.org>`_
73+
- Display information about your commit rules (commands: schema, example, info)
74+
- Bump version automatically using semantic verisoning based on the commits. `Read More <./docs/bump.md>`_
75+
- Generate a changelog using "Keep a changelog" (Planned feature)
7476

7577

7678
Commit rules
@@ -84,7 +86,6 @@ This is an example of how the git messages history would look like:
8486

8587
::
8688

87-
BREAKING CHANGE: command send has been removed
8889
fix: minor typos in code
8990
feat: new command update
9091
docs: improved commitizens tab in readme
@@ -95,6 +96,12 @@ This is an example of how the git messages history would look like:
9596
docs(README): added about, installation, creating, etc
9697
feat(config): new loads from ~/.cz and working project .cz .cz.cfg and setup.cfg
9798

99+
And then using ``cz bump`` you can change the version of your project
100+
101+
``feat`` to ``MINOR``
102+
``fix`` to ``PATCH``
103+
104+
98105
Commitizens
99106
===========
100107

@@ -155,142 +162,6 @@ Usage
155162
schema show commit schema
156163
bump bump semantic version based on the git log
157164

158-
159-
Configuration
160-
==============
161-
162-
**New!**: Support for ``pyproject.toml``
163-
164-
In your ``pyproject.toml`` you can add an entry like this:
165-
166-
::
167-
168-
[tool.commitizen]
169-
name = cz_conventional_commits
170-
version = "0.1.0"
171-
files = [
172-
"src/__version__.py",
173-
"pyproject.toml"
174-
]
175-
176-
177-
Also, you can create in your project folder a file called
178-
:code:`.cz`, :code:`.cz.cfg` or in your :code:`setup.cfg`
179-
or if you want to configure the global default in your user's home
180-
folder a :code:`.cz` file with the following information:
181-
182-
::
183-
184-
[commitizen]
185-
name = cz_conventional_commits
186-
version = 0.1.0
187-
files = [
188-
"src/__version__.py",
189-
"pyproject.toml"
190-
]
191-
192-
The extra tab at the end (``]``) is required.
193-
194-
Creating a commiter
195-
========================
196-
197-
Create a file starting with :code:`cz_` for example :code:`cz_jira.py`.
198-
This prefix is used to detect the plugin. Same method `flask uses <http://flask.pocoo.org/docs/0.12/extensiondev/>`_
199-
200-
Inherit from :code:`BaseCommitizen` and you must define :code:`questions`
201-
and :code:`message`. The others are optionals.
202-
203-
204-
.. code-block:: python
205-
206-
from commitizen import BaseCommitizen
207-
208-
class JiraCz(BaseCommitizen):
209-
210-
def questions(self):
211-
"""Questions regarding the commit message.
212-
213-
:rtype: list
214-
"""
215-
questions = [
216-
{
217-
'type': 'input',
218-
'name': 'title',
219-
'message': 'Commit title'
220-
},
221-
{
222-
'type': 'input',
223-
'name': 'issue',
224-
'message': 'Jira Issue number:'
225-
},
226-
]
227-
return questions
228-
229-
def message(self, answers):
230-
"""Generate the message with the given answers.
231-
232-
:type answers: dict
233-
:rtype: string
234-
"""
235-
return '{0} (#{1})'.format(answers['title'], answers['issue'])
236-
237-
def example(self):
238-
"""Provide an example to help understand the style (OPTIONAL)
239-
Used by cz example.
240-
241-
:rtype: string
242-
"""
243-
return 'Problem with user (#321)'
244-
245-
def schema(self):
246-
"""Show the schema used (OPTIONAL)
247-
248-
:rtype: string
249-
"""
250-
return '<title> (<issue>)'
251-
252-
def info(self):
253-
"""Explanation of the commit rules. (OPTIONAL)
254-
:rtype: string
255-
"""
256-
return 'We use this because is useful'
257-
258-
259-
discover_this = JiraCz # used by the plugin system
260-
261-
262-
The next file required is :code:`setup.py` modified from flask version
263-
264-
.. code-block:: python
265-
266-
from distutils.core import setup
267-
268-
setup(
269-
name='JiraCommitizen',
270-
version='0.1.0',
271-
py_modules=['cz_jira'],
272-
license='MIT',
273-
long_description='this is a long description',
274-
install_requires=['commitizen']
275-
)
276-
277-
So at the end we would have
278-
279-
::
280-
281-
.
282-
├── cz_jira.py
283-
└── setup.py
284-
285-
And that's it, you can install it without uploading to pypi by simply doing
286-
:code:`pip install .` If you feel like it should be part of the repo, create a
287-
PR.
288-
289-
Python 2 support
290-
=================
291-
292-
There's no longer support for python 2. Nor planned suppport.
293-
294165
Contributing
295166
============
296167

@@ -299,4 +170,4 @@ Feel free to create a PR.
299170
1. Clone the repo.
300171
2. Add your modifications
301172
3. Create a virtualenv
302-
4. Run :code:`pytest -s --cov-report term-missing --cov=commitizen tests/`
173+
4. Run :code:`./scripts/test`

‎docs/bump.md‎

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
## About
2+
3+
The version is bumped **automatically** based on the commits.
4+
5+
The commits should follow the rules of the commiter in order to be parsed properly.
6+
7+
It is possible to specify a **prerelease** (alpha, beta, release candidate) version.
8+
9+
The version can also be **manually** bumped.
10+
11+
The version format follows [semantic versioning][semver].
12+
13+
This means `MAJOR.MiNOR.PATCH`
14+
15+
| Increment | Description | Conventional commit map |
16+
| ------- | ----- | ------ |
17+
| `MAJOR` | Breaking changes introduced | `BREAKING CHANGE` |
18+
| `MINOR` | New features | `feat` |
19+
| `PATCH` | Fixes | `fix` + everything else |
20+
21+
22+
Prereleases are supported following python's [PEP 0440][pep440]
23+
24+
The scheme of this format is
25+
26+
```
27+
[N!]N(.N)*[{a|b|rc}N][.postN][.devN]
28+
```
29+
30+
Some examples:
31+
32+
```
33+
0.9.0
34+
0.9.1
35+
0.9.2
36+
0.9.10
37+
0.9.11
38+
1.0.0a0 # alpha
39+
1.0.0a1
40+
1.0.0b0 # beta
41+
1.0.0rc0 # release candidate
42+
1.0.0rc1
43+
1.0.0
44+
1.0.1
45+
1.1.0
46+
2.0.0
47+
2.0.1a
48+
```
49+
50+
`post` and `dev` releases are not supported yet.
51+
52+
## Usage
53+
54+
```bash
55+
$ cz bump --help
56+
usage: cz bump [-h] [--dry-run] [--tag-format TAG_FORMAT]
57+
[--prerelease {alpha,beta,rc}]
58+
[--increment {MAJOR,MINOR,PATCH}]
59+
60+
optional arguments:
61+
-h, --help show this help message and exit
62+
--dry-run show output to stdout, no commit, no modified files
63+
--tag-format TAG_FORMAT
64+
format used to tag the commmit and read it, use it in
65+
existing projects, wrap around simple quotes.
66+
--prerelease {alpha,beta,rc}, -pr {alpha,beta,rc}
67+
choose type of prerelease
68+
--increment {MAJOR,MINOR,PATCH}
69+
manually specify the desired increment
70+
```
71+
72+
73+
## Configuration
74+
75+
`tag_format`
76+
77+
Used to read the format from the git tags, and also to generate the tags.
78+
79+
Supports 2 types of formats, a simple and a more complex.
80+
81+
```bash
82+
cz bump --tag_format="v$version"
83+
```
84+
85+
```bash
86+
cz bump --tag_format="v$minor.$major.$path$prerelease"
87+
```
88+
89+
In your `pyproject.toml`
90+
91+
```toml
92+
[commitizen]
93+
tag_format = "v$minor.$major.$path$prerelease"
94+
```
95+
96+
The variables must be preceded by a `$` sign.
97+
98+
Suppported variables:
99+
100+
| Variable | Description |
101+
| --- | ----------- |
102+
| `$version` | full generated version |
103+
| `$major` | MAJOR increment |
104+
| `$minor` | MINOR increment |
105+
| `$patch` | PATCH increment |
106+
| `$prerelease` | Prerelase (alpha, beta, release candidate) |
107+
108+
`files`
109+
110+
Used to identify the files which should be updated with the new version.
111+
In your `pyproject.toml`
112+
113+
Commitizen will update it's configuration (`pyproject.toml`, `.cz`) when bumping.
114+
115+
```toml
116+
[commitizen]
117+
files = [
118+
"src/__version__.py",
119+
"setup.py"
120+
]
121+
```
122+
123+
[pep440]: https://www.python.org/dev/peps/pep-0440/
124+
[semver]: https://semver.org/

‎docs/config.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# Configuration
2+
3+
**New!**: Support for `pyproject.toml`
4+
5+
Add an entry to `pyproject.toml`.
6+
7+
8+
[tool.commitizen]
9+
name = "cz_conventional_commits"
10+
version = "0.1.0"
11+
files = [
12+
"src/__version__.py",
13+
"pyproject.toml"
14+
]
15+
16+
17+
Also, you can create in your project folder a file called `.cz`,
18+
`.cz.cfg` or in your `setup.cfg` or if you want to configure the global
19+
default in your user's home folder a `.cz` file with the following
20+
information:
21+
22+
[commitizen]
23+
name = cz_conventional_commits
24+
version = 0.1.0
25+
files = [
26+
"src/__version__.py",
27+
"pyproject.toml"
28+
]
29+
30+
The extra tab at the end (`]`) is required.
31+
32+
## settings
33+
34+
| Variable | Type | Default | Description |
35+
| -------- | ---- | ------- | ----------- |
36+
| name | str | `"cz_conventional_commits"` | Name of the commiting rules to use |
37+
| version | str | `None` | Current version. Example: "0.1.2" |
38+
| files | list | `[ ]` | Files were the version needs to be updated |
39+
| 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) |

0 commit comments

Comments
(0)

AltStyle によって変換されたページ (->オリジナル) /