From b0235e52cb00bef1d0ac9fd20514c6641e67137c Mon Sep 17 00:00:00 2001 From: Yu-Ting Hsiung Date: Tue, 13 Jan 2026 22:38:05 +0800 Subject: [PATCH] docs(changelog): fix minor mistakes in changelog documentation, improve fluency --- docs/commands/changelog.md | 75 +++++++++++++++++++------------------- 1 file changed, 37 insertions(+), 38 deletions(-) diff --git a/docs/commands/changelog.md b/docs/commands/changelog.md index 3f2425a51..da40eb6fb 100644 --- a/docs/commands/changelog.md +++ b/docs/commands/changelog.md @@ -1,6 +1,6 @@ ## About -This command will generate a changelog following the committing rules established. +Generates a changelog following the committing rules established. !!! tip To create the changelog automatically on bump, add the setting [update_changelog_on_bump](../config/bump.md#update_changelog_on_bump) @@ -20,7 +20,7 @@ This command will generate a changelog following the committing rules establishe # Generate full changelog cz changelog -# or use the alias +# Or use the alias cz ch # Get the changelog for the given version @@ -30,7 +30,7 @@ cz changelog 0.3.0 --dry-run cz changelog 0.3.0..0.4.0 --dry-run ``` -## Constrains +## Constraints Changelog generation is constrained only to **markdown** files. @@ -46,30 +46,30 @@ These are the variables used by the changelog generator. - ****: ``` -It will create a full block like above per version found in the tags. -And it will create a list of the commits found. -The `change_type` and the `scope` are optional, they don't need to be provided, -but if your regex does, they will be rendered. +Creates a full block like above per version found in the tags, and a list of the commits found. +The `change_type` and `scope` are optional and don't need to be provided, +but if your regex parses them, they will be rendered. -The format followed by the changelog is the one from [keep a changelog][keepachangelog] +The format followed by the changelog is from [keep a changelog][keepachangelog] and the following variables are expected: | Variable | Description | Source | | ------------- | ---------------------------------------------------------------------------------------------- | -------------- | | `version` | Version number which should follow [semver][semver] | `tags` | -| `date` | Date in which the tag was created | `tags` | +| `date` | Date when the tag was created | `tags` | | `change_type` | The group where the commit belongs to, this is optional. Example: fix | `commit regex` | -| `message`\* | Information extracted from the commit message | `commit regex` | +| `message` | Information extracted from the commit message | `commit regex` | | `scope` | Contextual information. Should be parsed using the regex from the message, it will be **bold** | `commit regex` | -| `breaking` | Whether is a breaking change or not | `commit regex` | +| `breaking` | Whether it is a breaking change or not | `commit regex` | -- **required**: is the only one required to be parsed by the regex +!!! note + `message` is the only variable required to be parsed by the regex. ## Command line options ### `--extras` -Provides your own changelog extra variables by using the `extras` settings or the `--extra/-e` parameter. +Provide your own changelog extra variables by using the `extras` settings or the `--extra/-e` parameter. ```bash cz changelog --extra key=value -e short="quoted value" @@ -77,9 +77,9 @@ cz changelog --extra key=value -e short="quoted value" ### `--file-name` -This value can be updated in the configuration file with the key `changelog_file` under `tools.commitizen` +This value can be updated in the configuration file with the key `changelog_file` under `tool.commitizen`. -Specify the name of the output file, remember that changelog only works with Markdown. +Specify the name of the output file. Note that changelog generation only works with Markdown files. ```bash cz changelog --file-name="CHANGES.md" @@ -87,27 +87,27 @@ cz changelog --file-name="CHANGES.md" ### `--incremental` -This flag can be set in the configuration file with the key `changelog_incremental` under `tools.commitizen` +This flag can be set in the configuration file with the key `changelog_incremental` under `tool.commitizen` Benefits: -- Build from the latest version found in changelog, this is useful if you have a different changelog and want to use commitizen +- Build from the latest version found in changelog. This is useful if you have an existing changelog and want to use commitizen to extend it. - Update unreleased area -- Allows users to manually touch the changelog without being rewritten. +- Allows users to manually edit the changelog without it being completely rewritten. ```bash cz changelog --incremental ``` ```toml -[tools.commitizen] +[tool.commitizen] # ... changelog_incremental = true ``` ### `--start-rev` -This value can be set in the configuration file with the key `changelog_start_rev` under `tools.commitizen` +This value can be set in the configuration file with the key `changelog_start_rev` under `tool.commitizen` Start from a given git rev to generate the changelog. Commits before that rev will not be considered. This is especially useful for long-running projects adopting conventional commits, where old commit messages might fail to be parsed for changelog generation. @@ -116,43 +116,43 @@ cz changelog --start-rev="v0.2.0" ``` ```toml -[tools.commitizen] +[tool.commitizen] # ... changelog_start_rev = "v0.2.0" ``` ### `--merge-prerelease` -This flag can be set in the configuration file with the key `changelog_merge_prerelease` under `tools.commitizen` +This flag can be set in the configuration file with the key `changelog_merge_prerelease` under `tool.commitizen` -Collects changes from prereleases into the next non-prerelease. This means that if you have a prerelease version, and then a normal release, the changelog will show the prerelease changes as part of the changes of the normal release. If not set, it will include prereleases in the changelog. +Collects changes from prereleases into the next non-prerelease version. If you have a prerelease version followed by a normal release, the changelog will show the prerelease changes as part of the normal release. If not set, prereleases will be included as separate entries in the changelog. ```bash cz changelog --merge-prerelease ``` ```toml -[tools.commitizen] +[tool.commitizen] # ... changelog_merge_prerelease = true ``` ### `--template` -Provides your own changelog jinja template by using the `template` settings or the `--template` parameter. +Provide your own changelog Jinja template by using the `template` settings or the `--template` parameter. + +```bash +cz changelog --template="path/to/template.j2" +``` ### `--unreleased-version` -There is usually a chicken and egg situation when automatically -bumping the version and creating the changelog. -If you bump the version first, you have no changelog, you have to -create it later, and it won't be included in -the release of the created version. +There is usually a chicken-and-egg situation when automatically bumping the version and creating the changelog: -If you create the changelog before bumping the version, then you -usually don't have the latest tag, and the _Unreleased_ title appears. +- If you bump the version first, you have no changelog yet, and it won't be included in the release of the created version. +- If you create the changelog before bumping the version, you usually don't have the latest tag, and the _Unreleased_ title appears. -By introducing `--unreleased-version` you can prevent this situation. +By using `--unreleased-version`, you can prevent this situation. Before bumping you can run: @@ -160,12 +160,11 @@ Before bumping you can run: cz changelog --unreleased-version="v1.0.0" ``` -Remember to use the tag instead of the raw version number +Remember to use the tag format instead of the raw version number. -For example if the format of your tag includes a `v` (`v1.0.0`), then you should use that, -if your tag is the same as the raw version, then ignore this. +For example, if your tag format includes a `v` prefix (e.g., `v1.0.0`), use that format. If your tag is the same as the raw version (e.g., `1.0.0`), use the raw version. -Alternatively you can directly bump the version and create the changelog by doing +Alternatively, you can directly bump the version and create the changelog by running: ```bash cz bump --changelog @@ -175,7 +174,7 @@ cz bump --changelog Supported hook methods: -- Per parsed message: Useful to add links +- Per parsed message: Useful to add links to commits or issues - End of changelog generation: Useful to send Slack or chat messages, or notify another department Read more about hooks in the [customization page][customization]