Skip to content

Commit f863eae

Browse files
Lee-WLee-W
committed
docs(cz/cz_customize): description for newly added customization functionality
#54
1 parent c1f3235 commit f863eae

File tree

2 files changed

+67
-3
lines changed

2 files changed

+67
-3
lines changed

‎docs/config.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -65,3 +65,4 @@ The extra tab before the square brakets (`]`) at the end is required.
6565
| `tag_format` | `str` | `None` | Format for the git tag, useful for old projects, that use a convention like `"v1.2.1"`. [See more](https://woile.github.io/commitizen/bump#tag_format) |
6666
| `bump_message` | `str` | `None` | Create custom commit message, useful to skip ci. [See more](https://woile.github.io/commitizen/bump#bump_message) |
6767
| `style` | `list` | see above | Style for the prompts (It will merge this value with default style.) [See More (Styling your prompts with your favorite colors)](https://github.com/tmbo/questionary#additional-features) |
68+
| `customize` | `dict` | `None` | **This is only supported when config through `toml`.** Custom rules for committing and bumping. [See more](https://woile.github.io/commitizen/customization/) |

‎docs/customization.md

Lines changed: 66 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
Customizing commitizen is not hard at all.
22

3+
## Customize through customize class
4+
35
The basic steps are:
46

57
1. Inheriting from `BaseCommitizen`
@@ -9,7 +11,7 @@ The basic steps are:
911

1012
Check an [example](convcomms) on how to configure `BaseCommitizen`.
1113

12-
## Custom commit rules
14+
### Custom commit rules
1315

1416
Create a file starting with `cz_` for example `cz_jira.py`. This prefix
1517
is used to detect the plugin. Same method [flask uses]
@@ -95,7 +97,7 @@ If you feel like it should be part of this repo, create a PR.
9597

9698
[flask uses]: http://flask.pocoo.org/docs/0.12/extensiondev/
9799

98-
## Custom bump rules
100+
### Custom bump rules
99101

100102
You need to define 2 parameters inside `BaseCommitizen`.
101103

@@ -123,7 +125,7 @@ cz -n cz_strange bump
123125

124126
[convcomms]: https://github.com/Woile/commitizen/blob/master/commitizen/cz/conventional_commits/conventional_commits.py
125127

126-
## Raise Customize Exception
128+
### Raise Customize Exception
127129

128130
If you wannt `commitizen` to catch your exception and print the message, you'll have to inherit `CzException`.
129131

@@ -133,3 +135,64 @@ from commitizen.cz.exception import CzException
133135
class NoSubjectProvidedException(CzException):
134136
...
135137
```
138+
139+
## Customize in toml
140+
141+
**This is only supported when configuring through `toml` (e.g., `pyproject.toml`, `.cz`, and `.cz.toml`)**
142+
143+
The basic steps are:
144+
1. Define your custom committing or bumpping rules in the configuration file.
145+
2. Declare `name = "cz_customize"` in your configuration file, or add `-n cz_customize` when running commitizen.
146+
147+
Example:
148+
149+
```toml
150+
[tool.commitizen]
151+
name = "cz_customize"
152+
153+
[tool.commitizen.customize]
154+
message_template = "{change_type}: {message}"
155+
example = "feature: this feature eanable customize through config file"
156+
schema = "<type>: <body>"
157+
bump_pattern = "^(break|new|fix|hotfix)"
158+
bump_map = {"break" = "MAJOR", "new" = "MINOR", "fix" = "PATCH", "hotfix" = "PATCH"}
159+
info_path = "cz_customize_info.txt"
160+
info = """
161+
This is customized info
162+
"""
163+
164+
[[tool.commitizen.customize.questions]]
165+
type = "list"
166+
name = "change_type"
167+
choices = ["feature", "bug fix"]
168+
message = "Select the type of change you are committing"
169+
170+
[[tool.commitizen.customize.questions]]
171+
type = "input"
172+
name = "message"
173+
message = "Body."
174+
```
175+
176+
### Customize configuration
177+
178+
| Parameter | Type | Default | Description |
179+
| --------- | ---- | ------- | ----------- |
180+
| `question` | `dict` | `None` | Questions regarding the commit message. Detatiled below. |
181+
| `message_template` | `str` | `None` | The template for generating message from the given answers. `message_template` should follow the python string formatting specification, and all the variables in this template should be defined in `name` in `questions`. |
182+
| `example` | `str` | `None` | (OPTIONAL) Provide an example to help understand the style. Used by `cz example`. |
183+
| `schema` | `str` | `None` | (OPTIONAL) Show the schema used. Used by `cz schema`. |
184+
| `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. |
185+
| `info` | `str` | `None` | (OPTIONAL) Explanation of the commit rules. Used by `cz info`. |
186+
| `bump_map` | `dict` | `None` | (OPTIONAL) Dictionary mapping the extracted information to a `SemVer` increment type (`MAJOR`, `MINOR`, `PATCH`) |
187+
| `bump_pattern` | `str` | `None` | (OPTIONAL) Regex to extract information from commit (subject and body) |
188+
189+
#### Detailed `question` content
190+
191+
| Parameter | Type | Default | Description |
192+
| --------- | ---- | ------- | ----------- |
193+
| `type` | `str` | `None` | The type of questions. Valid type: `list`, `input` and etc. [See More](https://github.com/tmbo/questionary#different-question-types) |
194+
| `name` | `str` | `None` | The key for the value answered by user. It's used in `message_template` |
195+
| `message` | `str` | `None` | Detail description for the question. |
196+
| `choices` | `list` | `None` | (OPTIONAL) The choices when `type = choice`. It should be list of dictionaries with `name` and `value`. (e.g., `[{value = "feature", name = "feature: A new feature."}, {value = "bug fix", name = "bug fix: A bug fix."}]`) |
197+
| `default` | `Any` | `None` | (OPTIONAL) The default value for this question. |
198+
| `filter` | `str` | `None` | (Optional) Validator for user's answer. **(Work in Progress)** |

0 commit comments

Comments
 (0)