conventional-changelog - GitLite

KO | EN

gitlite — search

#javascript #hacktoberfest #react #ai #llm #golang #go #android #machine-learning #deep-learning #linux #cli #security #ios

conventional-changelog

(★ 176)

Conventional changelog plugin for release-it

File Explorer

Download Latest Version (.zip)

- - publish-pkg.pr.new.yml
  - test.yml
.gitignore
.prettierrc
index.js
LICENSE
package-lock.json
package.json
README.md
test.js

# Installation Guide

1. Get the code

git clone https://github.com/release-it/conventional-changelog

Downloads the entire project code from GitHub to your computer.

cd conventional-changelog

Moves into the project folder you just downloaded.

2. Node.js

Easy Recommended

Prerequisites

Git Needed to download the project code from GitHub.
Node.js Node.js must be installed to use npm. The LTS version is recommended.

npm install --save-dev @release-it/conventional-changelog

Downloads and installs the libraries listed in package.json.

npm ls conventional-commits-parser

Type this command into your terminal and run it.

✅ After running the command, open the address shown in the terminal (usually something like http://localhost:3000) in your browser.

Pulled directly from this repo's README.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Conventional Changelog plugin for release-it

This plugin will provide the recommended bump to release-it, and update the changelog file (e.g. `CHANGELOG.md`).

```
npm install --save-dev @release-it/conventional-changelog
```

## Configuration

In the [release-it][1] config, for example:

```json
"plugins": {
  "@release-it/conventional-changelog": {
    "preset": {
      "name": "angular"
    },
    "infile": "CHANGELOG.md"
  }
}
```

The plugin is a wrapper around conventional-changelog packages [conventional-recommended-bump][2],
[conventional-changelog][3] and more.

## Contents

- [`preset`][4]
- Bump
  - [`commitsOpts`][5]
  - [`tagOpts`][6]
  - [`whatBump`][7]
  - [`ignoreRecommendedBump`][8]
  - [`strictSemVer`][9]
- Changelog
  - [`infile`][10]
  - [`header`][11]
  - [`context`][12]
  - [`gitRawCommitsOpts`][13]
  - [`parserOpts`][14]
  - [`writerOpts`][15]

### `preset`

For `preset.name`, use one of:

- `angular`
- `atom`
- `codemirror`
- `conventionalcommits`
- `ember`
- `eslint`
- `express`
- `jquery`
- `jscs`
- `jshint`

Use an object with `name` and `types` to use a custom preset:

```json
"plugins": {
  "@release-it/conventional-changelog": {
    "infile": "CHANGELOG.md",
    "preset": {
      "name": "conventionalcommits",
      "types": [
        {
          "type": "feat",
          "section": "Features"
        },
        {
          "type": "fix",
          "section": "Bug Fixes"
        },
        {
          "type": "docs",
          "section": "Documentation",
          "effect": "changelog"
        },
        {
          "type": "chore",
          "effect": "hidden"
        }
      ]
    }
  }
}
```

This is passed as the first argument to [`bumper.loadPreset`][16] (in both bumper and changelog writer).

With the `conventionalcommits` preset, `types[].effect` controls changelog visibility and recommended bumps for
non-breaking commits:

- `bump` includes the commit in the changelog and bump recommendation. This is the default.
- `changelog` includes the commit in the changelog without triggering a bump.
- `hidden` excludes the commit from both.

Breaking changes still trigger a major bump regardless of their type effect. See the
[Conventional Commits preset options][17] for the full configuration contract.

## Bump

### `tagOpts`

- This option will be passed as the first argument to [`bumper.tag`][16]
- [Type definition for `tagOpts` → look for `GetSemverTagsParams`][18]

### `commitsOpts`

- This option will be passed as the first argument to [`bumper.commits`][16]
- [Type definition for `commitsOpts` → look for `GetCommitsParams`][18]

### `whatBump`

- This option will be passed as the first argument to [`bumper.bump`][16]
- [Type definition for `whatBump` → look for `Preset['whatBump']`][19]
- Use `false` to skip releasing a new version:

```json
{
  "plugins": {
    "@release-it/conventional-changelog": {
      "whatBump": false
    }
  }
}
```

- Use a function to manually provide a bump:

```js
module.exports = {
  plugins: {
    '@release-it/conventional-changelog': {
      whatBump: function () {
        return { releaseType: '10.0.1' };
      }
    }
  }
};
```

### `ignoreRecommendedBump`

Default value: `false`

Use `true` to ignore the recommended bump, and use the version provided by release-it (command line argument or prompt).

Note that the changelog preview shows the recommended bump, as the desired version isn't known yet in the release-it
process. The `infile` will have the correct version.

### `strictSemVer`

Default value: `false`

Use `true` to strictly follow semver, also in consecutive pre-releases. This means that from a pre-release, a
recommended bump will result in a next pre-release for the next version.

For example, from `1.0.0-alpha.0` a recommended bump of `minor` will result in a `preminor` bump to `1.1.0-alpha.0`.

The default behavior results in a `prerelease` bump to `1.0.0-alpha.1`.

### Promoting a pre-release

The release-it `git.tagExclude` option only affects release-it's version lookup. The recommended bump and changelog
writer have their own tag policies. Configure all three when a stable release should include every commit since the
previous stable version:

```json
{
  "git": {
    "tagExclude": "*.*.*-*"
  },
  "plugins": {
    "@release-it/conventional-changelog": {
      "tagOpts": {
        "skipUnstable": true
      },
      "writerOpts": {
        "generateOn": null
      }
    }
  }
}
```

`tagOpts.skipUnstable` calculates the recommendation from the previous stable tag. `writerOpts.generateOn: null` keeps
intermediate prerelease tags from splitting those commits into separate changelog blocks.

## Changelog

### `infile`

Default value: `undefined`

- Set a filename as `infile` to write the changelog to. If this file does not exist yet, it's created with the full
  history.
- When `infile` is not set, the changelog generated by this plugin will still be used as release notes for e.g. [GitHub
  Releases][20].
- Set `infile: false` to disable the changelog writing (and only use the recommended bump for the next version).

### `header`

Default value: `"# Changelog"`

Set the main header for the changelog document:

```json
{
  "plugins": {
    "@release-it/conventional-changelog": {
      "infile": "CHANGELOG.md",
      "header": "# Changelog",
      "preset": {
        "name": "conventionalcommits"
      }
    }
  }
}
```

### `context`

Default value: `undefined`

This option will be passed as the second argument (`context`) to [conventional-changelog][21], for example:

```json
"plugins": {
  "@release-it/conventional-changelog": {
    "context": {
      "linkCompare": false
    }
  }
}
```

### `gitRawCommitsOpts`

Default value: `undefined`

Options for [`git-raw-commits`][22]. For example, you can use the following option to include merge commits into
changelog:

```json
{
  "plugins": {
    "@release-it/conventional-changelog": {
      "gitRawCommitsOpts": {
        "merges": null
      }
    }
  }
}
```

### `parserOpts`

- Default value: `undefined`
- Options for [`conventional-commits-parser`][23]
- This option will also be passed as the second argument to [`bumper.parserOptions`][16]
- [Type definition for `parserOpts` → look for `ParserOptions`][24]

For example, you can use the following option to set the merge pattern during parsing the commit message:

```json
{
  "plugins": {
    "@release-it/conventional-changelog": {
      "parserOpts": {
        "mergePattern": "^Merge pull request #(\\d+) from (.*)$"
      }
    }
  }
}
```

### `writerOpts`

- Default value: `undefined`
- Options for [`conventional-changelog-writer`][25]
- [Type definition for `writerOpts` → look for `Options`][26]

For example, you can use the following option to group the commits by 'scope' instead of 'type' by default.

```json
{
  "plugins": {
    "@release-it/conventional-changelog": {
      "writerOpts": {
        "groupBy": "scope"
      }
    }
  }
}
```

Customize the render functions in a `.release-it.js` file:

```js
module.exports = {
  plugins: {
    '@release-it/conventional-changelog': {
      writerOpts: {
        commitPartial: (_context, commit) => `- ${commit.header}`
      }
    }
  }
};
```

`template`, `headerPartial`, `preamblePartial`, `commitPartial`, and `footerPartial` accept render functions.
Handlebars template strings and partial files are no longer supported.

A custom `writerOpts.transform` **replaces** the preset's own transform (the one that maps commit types to
sections via [`preset.types`](#preset) and strips types with `effect: "hidden"`). Override it and you lose that
behavior. Raw types and hidden entries reappear. To filter or reshape the output while keeping the preset behavior, use
[`finalizeContext`][26] instead.

Since `conventional-changelog-writer@9`, the `commit` passed to `transform` is **read-only**. Return an
extended object instead of mutating it:

```js
// Wrong: no-op or throws, the commit is read-only
transform: commit => { commit.scope = '...'; return commit; }

// Right: return an extended copy
transform: commit => ({ ...commit, scope: '...' })
```

## Command-line

Options for this plugin can be set from the command line. Some examples:

```
release-it --plugins.@release-it/conventional-changelog.infile=history.md
release-it --no-plugins.@release-it/conventional-changelog.infile
```

- Keys are separated by dots.
- Values can be negated by prefixing the key with `no-`.
- Arguments may need to be single-quoted (`'`) such as `--'deep.key=value'` or `'--deep.key=value'`

Depending on your shell or OS this may differ.

## GitHub Actions

When using this plugin in a GitHub Action, make sure to set [`fetch-depth: 0`][27] so the history is available to
determine the correct recommended bump and changelog.

Also see [https://github.com/release-it/release-it/blob/main/docs/ci.md#github-actions][28]

## Troubleshooting

### `parseCommits is not a function`

`@conventional-changelog/git-client` dynamically imports [`conventional-commits-parser`][23] and needs
**v7**. This error means your dependency tree resolved an older incompatible version. Usually another dependency
(e.g. `@commitlint/cli`) pulls in an older version, and `legacy-peer-deps=true` (or the yarn/pnpm equivalent) lets it
win over git-client's `^7` peer requirement.

Check which version is resolved:

```
npm ls conventional-commits-parser
```

Then fix it on your side with one of:

- Force a single v7 via `overrides` (npm) / `resolutions` (yarn) / `pnpm.overrides`:
  ```json
  {
    "overrides": {
      "conventional-commits-parser": "^7"
    }
  }
  ```
- Remove `legacy-peer-deps=true` from your `.npmrc` so the `^7` peer requirement is honored.
- Update the conflicting dependency (e.g. `@commitlint/*`) to a version that uses v7.

[1]: https://github.com/release-it/release-it
[2]:
  https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-recommended-bump#readme
[3]:
  https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog#readme
[4]: #preset
[5]: #commitsopts
[6]: #tagopts
[7]: #whatbump
[8]: #ignorerecommendedbump
[9]: #strictsemver
[10]: #infile
[11]: #header
[12]: #context
[13]: #gitrawcommitsopts
[14]: #parseropts
[15]: #writeropts
[16]:
  https://github.com/conventional-changelog/conventional-changelog/blob/master/packages/conventional-recommended-bump/README.md#api
[17]: https://conventional-changelog.js.org/presets/conventional-commits/
[18]: https://github.com/conventional-changelog/conventional-changelog/blob/master/packages/git-client/src/types.ts
[19]:
  https://github.com/conventional-changelog/conventional-changelog/blob/master/packages/conventional-recommended-bump/src/types.ts
[20]: https://github.com/release-it/release-it/blob/main/docs/github-releases.md
[21]:
  https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog#readme
[22]: https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/git-raw-commits#api
[23]:
  https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-commits-parser#api
[24]:
  https://github.com/conventional-changelog/conventional-changelog/blob/master/packages/conventional-commits-parser/src/types.ts
[25]:
  https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-writer#api
[26]:
  https://github.com/conventional-changelog/conventional-changelog/blob/master/packages/conventional-changelog-writer/src/types/options.ts
[27]: https://github.com/actions/checkout#fetch-all-history-for-all-tags-and-branches
[28]: https://github.com/release-it/release-it/blob/main/docs/ci.md#github-actions