From 2abd2a8da5d37a55ae3cb873969547fd04f605ee Mon Sep 17 00:00:00 2001 From: Christopher Cyclonit Klinge Date: Fri, 14 Jun 2024 16:23:54 +0200 Subject: [PATCH] docs(changelog): update documentation related to changelog templates --- website/docs/configuration/changelog.md | 12 +- website/docs/templating/context.md | 242 ++++++++++++++---------- 2 files changed, 152 insertions(+), 102 deletions(-) diff --git a/website/docs/configuration/changelog.md b/website/docs/configuration/changelog.md index 22fae40840..0ccd441d5a 100644 --- a/website/docs/configuration/changelog.md +++ b/website/docs/configuration/changelog.md @@ -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. diff --git a/website/docs/templating/context.md b/website/docs/templating/context.md index 2afebdf4f5..184c4294f3 100644 --- a/website/docs/templating/context.md +++ b/website/docs/templating/context.md @@ -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** ``` [scope]: @@ -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": " (overridden by commit_parsers)", + "scope": "[scope]", + "message": "", + "body": "[body]", + "footers": [ { - "id": "e795460c9bb7275294d1fa53a9d73258fb51eb10", - "group": " (overridden by commit_parsers)", - "scope": "[scope]", - "message": "", - "body": "[body]", - "footers": [ - { - "token": "", - "separator": "", - "value": "", - "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": "", + "separator": "", + "value": "", + "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). @@ -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.