Skip to content

Commit

Permalink
docs(changelog): update documentation related to changelog templates
Browse files Browse the repository at this point in the history
  • Loading branch information
@Cyclonit
Cyclonit committed Jun 14, 2024
1 parent 1cd6e0c commit 2abd2a8
Show file tree
Hide file tree
Showing 2 changed files with 152 additions and 102 deletions.
12 changes: 6 additions & 6 deletions website/docs/configuration/changelog.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,21 +24,21 @@ postprocessors = [{ pattern = "foo", replace = "bar"}]

### header

Header text that will be added to the beginning of the changelog.
Header template that will be rendered and added to the beginning of the changelog.

The header template's context contains a list of all releases in the variable `releases`. Refer to [templating](/docs/category/templating) for a detailed description of the available context.

### body

Body template that represents a single release in the changelog.
Body template that will be rendered for each release in the changelog.

See [templating](/docs/category/templating) for more detail.
The body template's context contains the current release in the variable `release`. Refer to [templating](/docs/category/templating) for a detailed description of the available context.

### footer

Footer template that will be rendered and added to the end of the changelog.

The template context is the same as [`body`](#body) and contains all the releases instead of a single release.

For example, to get the list of releases, use the `{{ releases }}` variable in the template. To get information about a single release, iterate over this array and access the fields similar to [`body`](#body).
The header template's context contains a list of all releases in the variable `releases`. Refer to [templating](/docs/category/templating) for a detailed description of the available context.

See [Keep a Changelog configuration](/docs/templating/examples#keep-a-changelog) for seeing the example of adding links to the end of the changelog.

Expand Down
242 changes: 146 additions & 96 deletions website/docs/templating/context.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,14 +4,45 @@ sidebar_position: 1

# Context

Context is the model that holds the required data for a template rendering. The [JSON](https://en.wikipedia.org/wiki/JSON) format is used in the following examples for the representation of a context.
Git-cliff uses [Tera](#https://keats.github.io/tera/docs/) for rendering templates. The context is a set of variables that can accessed from within the template.

## Conventional Commits
The examples on this page use [JSON](https://en.wikipedia.org/wiki/JSON) to represent the context's data structure. See the [Data structures](https://keats.github.io/tera/docs/#data-structures) section of the Tera documentation for details on how Tera handles variables internally.

> conventional_commits = **true**
## Release

For a [conventional commit](/docs/configuration/git#conventional_commits) like this,
**Example**
```json
{
"version": "v0.1.0-rc.21",
"commits": [
...
],
"commit_id": "a440c6eb26404be4877b7e3ad592bfaa5d4eb210",
"timestamp": 1625169301,
"previous": {
"version": "previous release"
}
}
```

**Properties**
- `version`
The release's version based on the release commit's tag. See the configuration option [`git.tag_pattern`](/docs/configuration/git#tag_pattern).
- `commits`
An array containing all commits being attributed to this release. Refer to the section [Commits](#commits) for the elements' structure. The array is ordered according to the configuration option [`git.sort_commits`](/docs/configuration/git#sort_commits).
- `commit_id`
The release commit's full sha-1 hash.
- `timestamp`
The unix epoch timestamp of the release commit. It can be used in combination with the [date filter](https://keats.github.io/tera/docs/#date) to print a human readable release date.
- `previous`
The previous version's version string.

## Commits
The data structure for commits within the release's commits property changes based on the configuration option [`git.conventional_commits`](/docs/configuration/git#conventional_commits). If set to `true`, each commit's message will be parsed according to the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification and result in the data structure in section [Conventional Commits](#conventional-commits). If set to `false` git-cliff will not attempt to parse the commits' message.

### Conventional Commits

**Example commit message**
```
<type>[scope]: <description>
Expand All @@ -20,60 +51,87 @@ For a [conventional commit](/docs/configuration/git#conventional_commits) like t
[footer(s)]
```

following context is generated to use for templating:

**Example Context**
```json
{
"version": "v0.1.0-rc.21",
"commits": [
"id": "e795460c9bb7275294d1fa53a9d73258fb51eb10",
"group": "<type> (overridden by commit_parsers)",
"scope": "[scope]",
"message": "<description>",
"body": "[body]",
"footers": [
{
"id": "e795460c9bb7275294d1fa53a9d73258fb51eb10",
"group": "<type> (overridden by commit_parsers)",
"scope": "[scope]",
"message": "<description>",
"body": "[body]",
"footers": [
{
"token": "<name of the footer, such as 'Signed-off-by'>",
"separator": "<the separator between the token and value, such as ':'>",
"value": "<the value following the separator",
"breaking": false
}
],
"breaking_description": "<description>",
"breaking": false,
"conventional": true,
"merge_commit": false,
"links": [
{ "text": "(set by link_parsers)", "href": "(set by link_parsers)" }
],
"author": {
"name": "User Name",
"email": "user.email@example.com",
"timestamp": 1660330071
},
"committer": {
"name": "User Name",
"email": "user.email@example.com",
"timestamp": 1660330071
}
"token": "<name of the footer, such as 'Signed-off-by'>",
"separator": "<the separator between the token and value, such as ':'>",
"value": "<the value following the separator",
"breaking": false
}
],
"commit_id": "a440c6eb26404be4877b7e3ad592bfaa5d4eb210 (release commit)",
"timestamp": 1625169301,
"previous": {
"version": "previous release"
"breaking_description": "<description>",
"breaking": false,
"conventional": true,
"merge_commit": false,
"links": [
{ "text": "(set by link_parsers)", "href": "(set by link_parsers)" }
],
"author": {
"name": "User Name",
"email": "user.email@example.com",
"timestamp": 1660330071
},
"committer": {
"name": "User Name",
"email": "user.email@example.com",
"timestamp": 1660330071
}
}
```

:::info

See the [GitHub integration](/docs/integration/github) for the additional values you can use in the template.

:::

### Footers
**Properties**
- `id`
The commit's full sha-1 hash.
- `group`
The group to which the commit belongs. Defaults to the `type` in the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification. Can be overridden by [`git.commit_parsers`](./../configuration/git#commit_parsers).
- `scope`
The commit's `scope` parsed from its original `message`.
- `message`
The commit's `description` parsed from its original `message`.
- `body`
The commit's `body` parsed from its original `message`.
- `footers`
See [Footers](#footers).
- `breaking_description`
See [Breaking Changes](#breaking-changes)
- `breaking`
See [Breaking Changes](#breaking-changes)
- `conventional`
`true` if the commit adhears to the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification, otherwise `false`.
- `merge_commit`
`true` if the commit is a merge commit, otherwise `false`.
- `links`
A list of links extracted from the commit's message using [`git.link_parsers`](/docs/configuration/git#link_parsers).
- `text`
The link text to be displayed to the user.
- `href`
The link's destination.
- `author`
The commit's original author. Not to be confused with `committer`. See [committer vs author](#committer-vs-author).
- `name`
The author's username as configured in their git configuration under `user.name`.
- `email`
The author's email as configured in their git configuration under `user.email`.
- `timestamp`
The unix epoch timestamp of when the author created the commit.
- `committer`
The person applying the commit. Not to be confused with `author`. See [committer vs author](#committer-vs-author).
- `name`
The committer's username as configured in their git configuration under `user.name`.
- `email`
The committer's email as configured in their git configuration under `user.email`.
- `timestamp`
The unix epoch timestamp of when the committer applied the commit to the codebase.

#### Footers

A conventional commit's body may end with any number of structured key-value pairs known as [footers](https://www.conventionalcommits.org/en/v1.0.0/#specification). These consist of a string token naming the footer, a separator (which is either `: ` or ` #`), and a value, similar to [the git trailers convention](https://git-scm.com/docs/git-interpret-trailers).

Expand All @@ -91,77 +149,69 @@ When a conventional commit contains footers, the footers are passed to the templ
- `value`, the value following the separator character
- `breaking`, which is `true` if this is a `BREAKING CHANGE:` footer, and `false` otherwise

### Breaking Changes
If you want to use a certain footer in a template, consider using the Tera filter [`filter`](https://keats.github.io/tera/docs/#filter) to extract the correct item from the list.

#### Breaking Changes

`breaking` flag is set to `true` when the commit has an exclamation mark after the commit type and scope, e.g.:
A commit is considered to be breaking if at least one of the following conditions holds true:

1. The commit has an exclamation mark `!` after the commit type and scope, e.g.:
```
feat(scope)!: this is a breaking change
```

Or when the `BREAKING CHANGE:` footer is defined:

2. The [footer](#footers) `BREAKING CHANGE:` is defined:
```
feat: add xyz
BREAKING CHANGE: this is a breaking change
```

`breaking_description` is set to the explanation of the breaking change. This description is expected to be present in the `BREAKING CHANGE` footer. However, if it's not provided, the `message` is expected to describe the breaking change.

If the `BREAKING CHANGE:` footer is present, the footer will also be included in
`commit.footers`.

Breaking changes will be skipped if [`protect_breaking_commits`](/docs/configuration/git#protect_breaking_commits) is set to `true`, even when matched by a skipping [commit_parser](/docs/configuration/git#commit_parsers).
If the footer `BREAKING CHANGE:` is present, the property `breaking_description` is set to the footer's value.

### Committer vs Author

From [Git docs](https://git-scm.com/book/en/v2/Git-Basics-Viewing-the-Commit-History):

> You may be wondering what the difference is between author and committer. The author is the person who originally wrote the work, whereas the committer is the person who last applied the work. So, if you send in a patch to a project and one of the core members applies the patch, both of you get credit — you as the author, and the core member as the committer.
If the footer `BREAKING CHANGE:` is present, it will be included in the list of the commit's footers.

## Non-Conventional Commits

> conventional_commits = **false**
If [`conventional_commits`](/docs/configuration/git#conventional_commits) is set to `false`, the message field will not be parsed. The following fields not be available:

If [`conventional_commits`](/docs/configuration/git#conventional_commits) is set to `false`, then some of the fields are omitted from the context or squashed into the `message` field:
- scope
- body
- footers
- breaking_description
- breaking

**Example**
```json
{
"version": "v0.1.0-rc.21",
"commits": [
{
"id": "e795460c9bb7275294d1fa53a9d73258fb51eb10",
"group": "(overridden by commit_parsers)",
"scope": "(overridden by commit_parsers)",
"message": "(full commit message including description, footers, etc.)",
"conventional": false,
"merge_commit": false,
"links": [
{ "text": "(set by link_parsers)", "href": "(set by link_parsers)" }
],
"author": {
"name": "User Name",
"email": "user.email@example.com",
"timestamp": 1660330071
},
"committer": {
"name": "User Name",
"email": "user.email@example.com",
"timestamp": 1660330071
}
}
"id": "e795460c9bb7275294d1fa53a9d73258fb51eb10",
"group": "(overridden by commit_parsers)",
"scope": "(overridden by commit_parsers)",
"message": "(full commit message including description, footers, etc.)",
"conventional": false,
"merge_commit": false,
"links": [
{ "text": "(set by link_parsers)", "href": "(set by link_parsers)" }
],
"commit_id": "a440c6eb26404be4877b7e3ad592bfaa5d4eb210 (release commit)",
"timestamp": 1625169301,
"previous": {
"version": "previous release"
"author": {
"name": "User Name",
"email": "user.email@example.com",
"timestamp": 1660330071
},
"committer": {
"name": "User Name",
"email": "user.email@example.com",
"timestamp": 1660330071
}
}
```

:::info
## Committer vs Author

From [Git docs](https://git-scm.com/book/en/v2/Git-Basics-Viewing-the-Commit-History):

> You may be wondering what the difference is between author and committer. The author is the person who originally wrote the work, whereas the committer is the person who last applied the work. So, if you send in a patch to a project and one of the core members applies the patch, both of you get credit — you as the author, and the core member as the committer.
See the [GitHub integration](/docs/integration/github) for the additional values you can use in the template.
## Integrations

:::
Git-cliff has integrations for [Atlassian Bitbucket](/docs/integration/bitbucket.md), [Github](/docs/integration/github.md) and [GitLab](/docs/integration/gitlab.md) repositories. They allow it to fetch additional metadata for commits and releases. Check the respective documentation to see how they contribute to the context.

0 comments on commit 2abd2a8

Please sign in to comment.