Skip to content

Commit 14f5de8

Browse files
Lee-WLee-W
committed
docs(customization): update title level
1 parent cbb9ad7 commit 14f5de8

File tree

1 file changed

+71
-70
lines changed

1 file changed

+71
-70
lines changed

‎docs/customization.md

+71-70
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,75 @@
11
Customizing commitizen is not hard at all.
2+
We have two different ways to do so.
23

3-
## Customize through customizing a class
4+
## 1. Customize in configuration file
5+
6+
**This is only supported when configuring through `toml` (e.g., `pyproject.toml`, `.cz`, and `.cz.toml`)**
7+
8+
The basic steps are:
9+
10+
1. Define your custom committing or bumping rules in the configuration file.
11+
2. Declare `name = "cz_customize"` in your configuration file, or add `-n cz_customize` when running commitizen.
12+
13+
Example:
14+
15+
```toml
16+
[tool.commitizen]
17+
name = "cz_customize"
18+
19+
[tool.commitizen.customize]
20+
message_template = "{{change_type}}:{% if show_message %} {{message}}{% endif %}"
21+
example = "feature: this feature enable customize through config file"
22+
schema = "<type>: <body>"
23+
bump_pattern = "^(break|new|fix|hotfix)"
24+
bump_map = {"break" = "MAJOR", "new" = "MINOR", "fix" = "PATCH", "hotfix" = "PATCH"}
25+
info_path = "cz_customize_info.txt"
26+
info = """
27+
This is customized info
28+
"""
29+
30+
[[tool.commitizen.customize.questions]]
31+
type = "list"
32+
name = "change_type"
33+
choices = [{value = "feature", name = "feature: A new feature."}, {value = "bug fix", name = "bug fix: A bug fix."}]
34+
# choices = ["feature", "fix"] # short version
35+
message = "Select the type of change you are committing"
36+
37+
[[tool.commitizen.customize.questions]]
38+
type = "input"
39+
name = "message"
40+
message = "Body."
41+
42+
[[tool.commitizen.customize.questions]]
43+
type = "confirm"
44+
name = "show_message"
45+
message = "Do you want to add body message in commit?"
46+
```
47+
48+
### Customize configuration
49+
50+
| Parameter | Type | Default | Description |
51+
| ------------------ | ------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
52+
| `questions` | `dict` | `None` | Questions regarding the commit message. Detailed below. |
53+
| `message_template` | `str` | `None` | The template for generating message from the given answers. `message_template` should either follow the [string.Template](https://docs.python.org/3/library/string.html#template-strings) or [Jinja2](https://jinja.palletsprojects.com/en/2.10.x/) formatting specification, and all the variables in this template should be defined in `name` in `questions`. Note that `Jinja2` is not installed by default. If not installed, commitizen will use `string.Template` formatting. |
54+
| `example` | `str` | `None` | (OPTIONAL) Provide an example to help understand the style. Used by `cz example`. |
55+
| `schema` | `str` | `None` | (OPTIONAL) Show the schema used. Used by `cz schema`. |
56+
| `info_path` | `str` | `None` | (OPTIONAL) The path to the file that contains explanation of the commit rules. Used by `cz info`. If not provided `cz info`, will load `info` instead. |
57+
| `info` | `str` | `None` | (OPTIONAL) Explanation of the commit rules. Used by `cz info`. |
58+
| `bump_map` | `dict` | `None` | (OPTIONAL) Dictionary mapping the extracted information to a `SemVer` increment type (`MAJOR`, `MINOR`, `PATCH`) |
59+
| `bump_pattern` | `str` | `None` | (OPTIONAL) Regex to extract information from commit (subject and body) |
60+
61+
#### Detailed `questions` content
62+
63+
| Parameter | Type | Default | Description |
64+
| --------- | ------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
65+
| `type` | `str` | `None` | The type of questions. Valid type: `list`, `input` and etc. [See More](https://github.com/tmbo/questionary#different-question-types) |
66+
| `name` | `str` | `None` | The key for the value answered by user. It's used in `message_template` |
67+
| `message` | `str` | `None` | Detail description for the question. |
68+
| `choices` | `list` | `None` | (OPTIONAL) The choices when `type = list`. Either use a list of values or a list of dicitionaries with `name` and `value` keys. See examples above. |
69+
| `default` | `Any` | `None` | (OPTIONAL) The default value for this question. |
70+
| `filter` | `str` | `None` | (Optional) Validator for user's answer. **(Work in Progress)** |
71+
72+
## 2. Customize through customizing a class
473

574
The basic steps are:
675

@@ -132,7 +201,7 @@ cz -n cz_strange bump
132201

133202
[convcomms]: https://github.com/commitizen-tools/commitizen/blob/master/commitizen/cz/conventional_commits/conventional_commits.py
134203

135-
## Custom changelog generator
204+
### Custom changelog generator
136205

137206
The changelog generator should just work in a very basic manner without touching anything.
138207
You can customize it of course, and this are the variables you need to add to your custom `BaseCommitizen`.
@@ -196,71 +265,3 @@ from commitizen.cz.exception import CzException
196265
class NoSubjectProvidedException(CzException):
197266
...
198267
```
199-
200-
## Customize in toml
201-
202-
**This is only supported when configuring through `toml` (e.g., `pyproject.toml`, `.cz`, and `.cz.toml`)**
203-
204-
The basic steps are:
205-
206-
1. Define your custom committing or bumping rules in the configuration file.
207-
2. Declare `name = "cz_customize"` in your configuration file, or add `-n cz_customize` when running commitizen.
208-
209-
Example:
210-
211-
```toml
212-
[tool.commitizen]
213-
name = "cz_customize"
214-
215-
[tool.commitizen.customize]
216-
message_template = "{{change_type}}:{% if show_message %} {{message}}{% endif %}"
217-
example = "feature: this feature enable customize through config file"
218-
schema = "<type>: <body>"
219-
bump_pattern = "^(break|new|fix|hotfix)"
220-
bump_map = {"break" = "MAJOR", "new" = "MINOR", "fix" = "PATCH", "hotfix" = "PATCH"}
221-
info_path = "cz_customize_info.txt"
222-
info = """
223-
This is customized info
224-
"""
225-
226-
[[tool.commitizen.customize.questions]]
227-
type = "list"
228-
name = "change_type"
229-
choices = [{value = "feature", name = "feature: A new feature."}, {value = "bug fix", name = "bug fix: A bug fix."}]
230-
# choices = ["feature", "fix"] # short version
231-
message = "Select the type of change you are committing"
232-
233-
[[tool.commitizen.customize.questions]]
234-
type = "input"
235-
name = "message"
236-
message = "Body."
237-
238-
[[tool.commitizen.customize.questions]]
239-
type = "confirm"
240-
name = "show_message"
241-
message = "Do you want to add body message in commit?"
242-
```
243-
244-
### Customize configuration
245-
246-
| Parameter | Type | Default | Description |
247-
| ------------------ | ------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
248-
| `questions` | `dict` | `None` | Questions regarding the commit message. Detailed below. |
249-
| `message_template` | `str` | `None` | The template for generating message from the given answers. `message_template` should either follow the [string.Template](https://docs.python.org/3/library/string.html#template-strings) or [Jinja2](https://jinja.palletsprojects.com/en/2.10.x/) formatting specification, and all the variables in this template should be defined in `name` in `questions`. Note that `Jinja2` is not installed by default. If not installed, commitizen will use `string.Template` formatting. |
250-
| `example` | `str` | `None` | (OPTIONAL) Provide an example to help understand the style. Used by `cz example`. |
251-
| `schema` | `str` | `None` | (OPTIONAL) Show the schema used. Used by `cz schema`. |
252-
| `info_path` | `str` | `None` | (OPTIONAL) The path to the file that contains explanation of the commit rules. Used by `cz info`. If not provided `cz info`, will load `info` instead. |
253-
| `info` | `str` | `None` | (OPTIONAL) Explanation of the commit rules. Used by `cz info`. |
254-
| `bump_map` | `dict` | `None` | (OPTIONAL) Dictionary mapping the extracted information to a `SemVer` increment type (`MAJOR`, `MINOR`, `PATCH`) |
255-
| `bump_pattern` | `str` | `None` | (OPTIONAL) Regex to extract information from commit (subject and body) |
256-
257-
#### Detailed `questions` content
258-
259-
| Parameter | Type | Default | Description |
260-
| --------- | ------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
261-
| `type` | `str` | `None` | The type of questions. Valid type: `list`, `input` and etc. [See More](https://github.com/tmbo/questionary#different-question-types) |
262-
| `name` | `str` | `None` | The key for the value answered by user. It's used in `message_template` |
263-
| `message` | `str` | `None` | Detail description for the question. |
264-
| `choices` | `list` | `None` | (OPTIONAL) The choices when `type = list`. Either use a list of values or a list of dicitionaries with `name` and `value` keys. See examples above. |
265-
| `default` | `Any` | `None` | (OPTIONAL) The default value for this question. |
266-
| `filter` | `str` | `None` | (Optional) Validator for user's answer. **(Work in Progress)** |

0 commit comments

Comments
 (0)