Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs(changelog): update documentation related to changelog templates
- Loading branch information
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -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. | ||
|
|
||
| ## 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 | ||
| { | ||
| "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": "[email protected]", | ||
| "timestamp": 1660330071 | ||
| }, | ||
| "committer": { | ||
| "name": "User Name", | ||
| "email": "[email protected]", | ||
| "timestamp": 1660330071 | ||
| } | ||
| } | ||
| ``` | ||
|
|
@@ -73,7 +84,7 @@ See the [GitHub integration](/docs/integration/github) for the additional values | |
|
|
||
| ::: | ||
|
|
||
| #### 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` 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). | ||
|
|
||
| ## Non-Conventional Commits | ||
|
|
||
| > conventional_commits = **false** | ||
|
|
@@ -128,38 +133,34 @@ If [`conventional_commits`](/docs/configuration/git#conventional_commits) is set | |
|
|
||
| ```json | ||
| { | ||
| "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": "[email protected]", | ||
| "timestamp": 1660330071 | ||
| }, | ||
| "committer": { | ||
| "name": "User Name", | ||
| "email": "[email protected]", | ||
| "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. | ||
|
|
||