diff --git a/website/docs/configuration/changelog.md b/website/docs/configuration/changelog.md index 22fae40840..2a94bd0720 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 detailled 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 detailled 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 detailled 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..8a189b1aa3 100644 --- a/website/docs/templating/context.md +++ b/website/docs/templating/context.md @@ -6,7 +6,28 @@ sidebar_position: 1 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. -## Conventional Commits +## Release + +A release contains information about multiple commits. The context for each release has the following structure. The array `commits` contains the individual commits' data according to section [Commits](#commits) + + +```json +{ + "version": "v0.1.0-rc.21", + "commits": [ + ... + ], + "commit_id": "a440c6eb26404be4877b7e3ad592bfaa5d4eb210 (release commit)", + "timestamp": 1625169301, + "previous": { + "version": "previous release" + } +} +``` + +## Commits + +### Conventional Commits > conventional_commits = **true** @@ -24,45 +45,35 @@ following context is generated to use for templating: ```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 } } ``` @@ -73,7 +84,7 @@ See the [GitHub integration](/docs/integration/github) for the additional values ::: -### Footers +#### 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,7 +102,7 @@ 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 +#### Breaking Changes `breaking` flag is set to `true` when the commit has an exclamation mark after the commit type and scope, e.g.: @@ -114,12 +125,6 @@ If the `BREAKING CHANGE:` footer is present, the footer will also be included in 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). -### 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. - ## Non-Conventional Commits > conventional_commits = **false** @@ -128,38 +133,34 @@ If [`conventional_commits`](/docs/configuration/git#conventional_commits) is set ```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 } } ``` +## 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. + :::info See the [GitHub integration](/docs/integration/github) for the additional values you can use in the template.