| 1 | # **release-notes-generator**
|
| 2 |
|
| 3 | [**semantic-release**](https://github.com/semantic-release/semantic-release) plugin to generate changelog content with [conventional-changelog](https://github.com/conventional-changelog/conventional-changelog)
|
| 4 |
|
| 5 | [](https://github.com/semantic-release/release-notes-generator/actions?query=workflow%3ATest+branch%3Amaster) [](https://www.npmjs.com/package/@semantic-release/release-notes-generator)
|
| 6 | [](https://www.npmjs.com/package/@semantic-release/release-notes-generator)
|
| 7 |
|
| 8 | | Step | Description |
|
| 9 | |-----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
| 10 | | `generateNotes` | Generate release notes for the commits added since the last release with [conventional-changelog](https://github.com/conventional-changelog/conventional-changelog). |
|
| 11 |
|
| 12 | ## Install
|
| 13 |
|
| 14 | ```bash
|
| 15 | $ npm install @semantic-release/release-notes-generator -D
|
| 16 | ```
|
| 17 |
|
| 18 | ## Usage
|
| 19 |
|
| 20 | The plugin can be configured in the [**semantic-release** configuration file](https://github.com/semantic-release/semantic-release/blob/master/docs/usage/configuration.md#configuration):
|
| 21 |
|
| 22 | ```json
|
| 23 | {
|
| 24 | "plugins": [
|
| 25 | ["@semantic-release/commit-analyzer", {
|
| 26 | "preset": "angular",
|
| 27 | "parserOpts": {
|
| 28 | "noteKeywords": ["BREAKING CHANGE", "BREAKING CHANGES", "BREAKING"]
|
| 29 | }
|
| 30 | }],
|
| 31 | ["@semantic-release/release-notes-generator", {
|
| 32 | "preset": "angular",
|
| 33 | "parserOpts": {
|
| 34 | "noteKeywords": ["BREAKING CHANGE", "BREAKING CHANGES", "BREAKING"]
|
| 35 | },
|
| 36 | "writerOpts": {
|
| 37 | "commitsSort": ["subject", "scope"]
|
| 38 | }
|
| 39 | }]
|
| 40 | ]
|
| 41 | }
|
| 42 | ```
|
| 43 |
|
| 44 | With this example:
|
| 45 | - the commits that contains `BREAKING CHANGE`, `BREAKING CHANGES` or `BREAKING` in their body will be considered breaking changes (by default the [angular preset](https://github.com/conventional-changelog/conventional-changelog/blob/master/packages/conventional-changelog-angular/index.js#L14) checks only for `BREAKING CHANGE` and `BREAKING CHANGES`)
|
| 46 | - the commits will be sorted in the changelog by `subject` then `scope` (by default the [angular preset](https://github.com/conventional-changelog/conventional-changelog/blob/master/packages/conventional-changelog-angular/index.js#L90) sort the commits in the changelog by `scope` then `subject`)
|
| 47 |
|
| 48 | ## Configuration
|
| 49 |
|
| 50 | ### Options
|
| 51 |
|
| 52 | | Option | Description | Default |
|
| 53 | |------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------|
|
| 54 | | `preset` | [conventional-changelog](https://github.com/conventional-changelog/conventional-changelog) preset (possible values: [`angular`](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-angular), [`atom`](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-atom), [`codemirror`](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-codemirror), [`ember`](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-ember), [`eslint`](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-eslint), [`express`](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-express), [`jquery`](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-jquery), [`jshint`](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-jshint), [`conventionalcommits`](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-conventionalcommits)). | [`angular`](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-angular) |
|
| 55 | | `config` | NPM package name of a custom [conventional-changelog](https://github.com/conventional-changelog/conventional-changelog) preset. | - |
|
| 56 | | `parserOpts` | Additional [conventional-commits-parser](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-commits-parser#conventionalcommitsparseroptions) options that will extends the ones loaded by `preset` or `config`. This is convenient to use a [conventional-changelog](https://github.com/conventional-changelog/conventional-changelog) preset with some customizations without having to create a new module. | - |
|
| 57 | | `writerOpts` | Additional [conventional-commits-writer](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-writer#options) options that will extends the ones loaded by `preset` or `config`. This is convenient to use a [conventional-changelog](https://github.com/conventional-changelog/conventional-changelog) preset with some customizations without having to create a new module. | - |
|
| 58 | | `host` | The host used to generate links to issues and commits. See [conventional-changelog-writer#host](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-writer#host). | The host from the [`repositoryurl` option](https://github.com/semantic-release/semantic-release/blob/master/docs/usage/configuration.md#repositoryurl). |
|
| 59 | | `linkCompare` | Whether to include a link to compare changes since previous release in the release note. | `true` |
|
| 60 | | `linkReferences` | Whether to include a link to issues and commits in the release note. See [conventional-changelog-writer#linkreferences](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-writer#linkreferences). | `true` |
|
| 61 | | `commit` | Keyword used to generate commit links (formatted as `<host>/<owner>/<repository>/<commit>/<commit_sha>`). See [conventional-changelog-writer#commit](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-writer#commit). | `commits` for Bitbucket repositories, `commit` otherwise |
|
| 62 | | `issue` | Keyword used to generate issue links (formatted as `<host>/<owner>/<repository>/<issue>/<issue_number>`). See [conventional-changelog-writer#issue](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-writer#issue). | `issue` for Bitbucket repositories, `issues` otherwise |
|
| 63 | | `presetConfig` | Additional configuration passed to the [conventional-changelog](https://github.com/conventional-changelog/conventional-changelog) preset. Used for example with [conventional-changelog-conventionalcommits](https://github.com/conventional-changelog/conventional-changelog-config-spec/blob/master/versions/2.0.0/README.md). | - |
|
| 64 |
|
| 65 | **Notes**: in order to use a `preset` it must be installed (for example to use the [eslint preset](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-eslint) you must install it with `npm install conventional-changelog-eslint -D`)
|
| 66 |
|
| 67 | **Note**: `config` will be overwritten by the values of `preset`. You should use either `preset` or `config`, but not both.
|
| 68 |
|
| 69 | **Note**: Individual properties of `parserOpts` and `writerOpts` will override ones loaded with an explicitly set `preset` or `config`. If `preset` or `config` are not set, only the properties set in `parserOpts` and `writerOpts` will be used.
|
| 70 |
|
| 71 | **Note**: For presets that expects a configuration object, such as [`conventionalcommits`](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-conventionalcommits), the `presetConfig` option **must** be set.
|