Skip to content

docs(changelog): fix minor mistakes in changelog documentation, improve fluency #1792

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
bearomorphism wants to merge 1 commit into
base: master
Choose a base branch
from
+37 −38
Open

docs(changelog): fix minor mistakes in changelog documentation, improve fluency #1792

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
75 changes: 37 additions & 38 deletions docs/commands/changelog.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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)
Expand All @@ -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
Expand All @@ -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.

Expand All @@ -46,68 +46,68 @@ These are the variables used by the changelog generator.
- **<scope>**: <message>
```

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"
```

### `--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"
```

### `--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.

Expand All @@ -116,56 +116,55 @@ 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:

```bash
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
Expand All @@ -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]
Expand Down