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 f26e3c1

Browse files
committed
docs: add new section getting started
1 parent 7b270d8 commit f26e3c1

File tree

5 files changed

+132
-61
lines changed

5 files changed

+132
-61
lines changed

‎docs/README.md‎

Lines changed: 8 additions & 60 deletions
Original file line numberDiff line numberDiff line change
@@ -24,9 +24,9 @@ and from that foundation, it can bump your project's version, create
2424
the changelog, and update files.
2525

2626
By default, commitizen uses [conventional commits][conventional_commits], but you
27-
can build your own set of rules, using different rules.
27+
can build your own set of rules, and publish them.
2828

29-
Using a standarized set of rules to write commits makes commits easier to read, and enforces writing
29+
Using a standarized set of rules to write commits, makes commits easier to read, and enforces writing
3030
descriptive commits.
3131

3232
### Features
@@ -40,7 +40,7 @@ descriptive commits.
4040

4141
## Requirements
4242

43-
Python 3.7+
43+
[Python](https://www.python.org/downloads/) 3.7+
4444

4545
[Git][gitscm] `1.8.5.2`+
4646

@@ -82,71 +82,19 @@ brew install commitizen
8282

8383
## Usage
8484

85-
### Committing
86-
87-
Run in your terminal
88-
89-
```bash
90-
cz commit
91-
```
92-
93-
or the shortcut
94-
95-
```bash
96-
cz c
97-
```
98-
99-
#### Sign off the commit
100-
101-
Run in the terminal
102-
103-
```bash
104-
cz commit --signoff
105-
```
106-
107-
or the shortcut
108-
109-
```bash
110-
cz commit -s
111-
```
112-
113-
### Integration with Pre-commit
114-
115-
Commitizen can lint your commit message for you with `cz check`.
116-
117-
You can integrate this in your [pre-commit](https://pre-commit.com/) config with:
118-
119-
```yaml
120-
---
121-
repos:
122-
- repo: https://github.com/commitizen-tools/commitizen
123-
rev: master
124-
hooks:
125-
- id: commitizen
126-
- id: commitizen-branch
127-
stages: [push]
128-
```
129-
130-
After the configuration is added, you'll need to run:
85+
Most of the time this is the only command you'll run:
13186

13287
```sh
133-
pre-commit install --hook-type commit-msg --hook-type pre-push
88+
cz bump
13489
```
13590

136-
If you aren't using both hooks, you needn't install both stages.
137-
138-
| Hook | Recommended Stage |
139-
| ----------------- | ----------------- |
140-
| commitizen | commit-msg |
141-
| commitizen-branch | pre-push |
142-
143-
Note that pre-commit discourages using `master` as a revision, and the above command will print a warning. You should replace the `master` revision with the [latest tag](https://github.com/commitizen-tools/commitizen/tags). This can be done automatically with:
91+
On top of that, you can use commitizen to assist you with the creation of commits:
14492

14593
```sh
146-
pre-commit autoupdate
94+
cz commit
14795
```
14896

149-
Read more about the `check` command [here](check.md).
97+
Read more in the section [Getting Started](./getting_started.md).
15098

15199
### Help
152100

‎docs/config.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,7 @@ version_files = [
4343
"src/__version__.py",
4444
"pyproject.toml:version"
4545
]
46+
update_changelog_on_bump = true
4647
style = [
4748
["qmark", "fg:#ff9d00 bold"],
4849
["question", "bold"],

‎docs/contributing.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,9 @@ If you're a first-time contributor, you can check the issues with [good first is
2222
(We use [CodeCov](https://codecov.io/) to ensure our test coverage does not drop.)
2323
7. Use [commitizen](https://github.com/commitizen-tools/commitizen) to do git commit. We follow [conventional commmits][conventional-commmits]
2424
8. Run `./scripts/format` and `./scripts/test` to ensure you follow the coding style and the tests pass.
25-
9. Update `README.md`. Do **not** update the `CHANGELOG.md`, it will be automatically created after merging to `master`.
25+
9. Optionally, update the `README.md`.
26+
9. **Do not** update the `CHANGELOG.md`, it will be automatically created after merging to `master`.
27+
10. **Do not** update the versions in the project, they will be automatically updated.
2628
10. If your changes are about documentation. Run `poetry run mkdocs serve` to serve documentation locally and check whether there is any warning or error.
2729
11. Send a [pull request](https://github.com/commitizen-tools/commitizen/pulls) 🙏
2830

‎docs/getting_started.md‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
## Initialize commitizen
2+
3+
If it's your first time, you'll need to create a commitizen configuration file.
4+
5+
The assistant utility will help you set up everything
6+
7+
```sh
8+
cz init
9+
```
10+
11+
Alternatively, create a file `.cz.toml` in your project's directory.
12+
13+
```toml
14+
[tool.commitizen]
15+
version = "0.1.0"
16+
update_changelog_on_bump = true
17+
```
18+
19+
## Usage
20+
21+
### Bump version
22+
23+
```sh
24+
cz bump
25+
```
26+
27+
This command will bump your project's version, and it will create a tag.
28+
29+
Because of the setting `update_changelog_on_bump`, bump will also create the **changelog**.
30+
You can also [update files](./bump.md#version_files).
31+
You can configure the [version type](./bump.md#version-type) and [version provider](./config.md#version-providers).
32+
33+
There are many more options available, please read the docs for the [bump command](./bump.md).
34+
35+
### Committing
36+
37+
Run in your terminal
38+
39+
```bash
40+
cz commit
41+
```
42+
43+
or the shortcut
44+
45+
```bash
46+
cz c
47+
```
48+
49+
#### Sign off the commit
50+
51+
Run in the terminal
52+
53+
```bash
54+
cz commit --signoff
55+
```
56+
57+
or the shortcut
58+
59+
```bash
60+
cz commit -s
61+
```
62+
63+
### Get project version
64+
65+
Running `cz version` will return the version of commitizen, but if you want
66+
your project's version you can run:
67+
68+
```sh
69+
cz version -p
70+
```
71+
72+
This can be useful in many situations, where otherwise, you would require a way
73+
to parse the version of your project. Maybe it's simple if you use a `VERSION` file,
74+
but once you start working with many different projects, it becomes tricky.
75+
76+
A common example is, when you need to send to slack, the changes for the version that you
77+
just created:
78+
79+
```sh
80+
cz changelog --dry-run "$(cz version -p)"
81+
```
82+
83+
### Integration with Pre-commit
84+
85+
Commitizen can lint your commit message for you with `cz check`.
86+
87+
You can integrate this in your [pre-commit](https://pre-commit.com/) config with:
88+
89+
```yaml
90+
---
91+
repos:
92+
- repo: https://github.com/commitizen-tools/commitizen
93+
rev: master
94+
hooks:
95+
- id: commitizen
96+
- id: commitizen-branch
97+
stages: [push]
98+
```
99+
100+
After the configuration is added, you'll need to run:
101+
102+
```sh
103+
pre-commit install --hook-type commit-msg --hook-type pre-push
104+
```
105+
106+
If you aren't using both hooks, you needn't install both stages.
107+
108+
| Hook | Recommended Stage |
109+
| ----------------- | ----------------- |
110+
| commitizen | commit-msg |
111+
| commitizen-branch | pre-push |
112+
113+
Note that pre-commit discourages using `master` as a revision, and the above command will print a warning. You should replace the `master` revision with the [latest tag](https://github.com/commitizen-tools/commitizen/tags). This can be done automatically with:
114+
115+
```sh
116+
pre-commit autoupdate
117+
```
118+
119+
Read more about the `check` command [here](check.md).

‎mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ edit_uri: ""
1010

1111
nav:
1212
- Introduction: 'README.md'
13+
- Getting Started: 'getting_started.md'
1314
- Commands:
1415
- Init: 'init.md'
1516
- Commit: 'commit.md'

0 commit comments

Comments
(0)

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