conventional-changelog

Generate a changelog from git metadata.

Changelog?

[!NOTE] You don't have to use the angular commit convention. For the best result of the tool to tokenize your commit and produce flexible output, it's recommended to use a commit convention.

---

Install   •   Usage   •   Recommended workflow   •   Why   •   Presets   •   JS API

---

Install

# pnpm
pnpm add conventional-changelog
# yarn
yarn add conventional-changelog
# npm
npm i conventional-changelog

Usage

conventional-changelog -p angular

This will not overwrite any previous changelogs. The above generates a changelog based on commits since the last semver tag that matches the pattern of "Feature", "Fix", "Performance Improvement" or "Breaking Changes".

If this is your first time using this tool and you want to generate all previous changelogs, you could do

conventional-changelog -p angular -r 0

This will overwrite any previous changelogs if they exist.

All available command line parameters can be listed using CLI: conventional-changelog --help.

[!TIP] You can alias your command or add it to your package.json. EG: "changelog": "conventional-changelog -p angular -r 0".

Recommended workflow

1. Make changes
2. Commit those changes
3. Make sure Travis turns green
4. Bump version in package.json
5. conventional-changelog
6. Commit package.json and CHANGELOG.md files
7. Tag
8. Push

The reason why you should commit and tag after conventional-changelog is that the CHANGELOG should be included in the new release, hence commits.from defaults to the latest semver tag.

With npm version

Using the npm scripts to our advantage with the following hooks:

{
  "scripts": {
    "version": "conventional-changelog -p angular && git add CHANGELOG.md"
  }
}

You could follow the following workflow

1. Make changes
2. Commit those changes
3. Pull all the tags
4. Run the npm version [patch|minor|major] command
5. Push

You could optionally add a preversion script to package your project or running a full suit of test. And a postversion script to clean your system and push your release and tags.

By adding a .npmrc you could also automate your commit message and set your tag prefix as such:

tag-version-prefix=""
message="chore(release): %s :tada:"

Why

• Easy fully automate changelog generation. You could still add more points on top of it.
• Ignoring reverted commits, templating with handlebars.js and links to references, etc.
• Intelligently setup defaults but yet fully configurable with presets of popular projects.
• Everything internally or externally is pluggable.
• A lot of tests and actively maintained.

Presets

• angular
• atom
• codemirror
• conventionalcommits
• ember
• eslint
• express
• jquery
• jshint

JS API

import { ConventionalChangelog } from 'conventional-changelog'

const generator = new ConventionalChangelog()
  .readPackage()
  .loadPreset('angular')

generator
  .writeStream()
  .pipe(process.stdout)

// or

for await (const chunk of generator.write()) {
  console.log(chunk)
}

new ConventionalChangelog(cwdOrGitClient: string | ConventionalGitClient = process.cwd())

Create a new instance of conventional-changelog generator. cwdOrGitClient is the current working directory or a ConventionalGitClient instance.

generator.loadPreset(preset: PresetParams): this

Load and set necessary params from a preset.

generator.config(config: Preset | Promise<Preset>): this

Set the config directly.

generator.readPackage(transform?: PackageTransform): this

Find package.json up the directory tree and read it. Optionally transform the package data.

generator.readPackage(path: string, transform?: PackageTransform): this

Read a package.json file from a specific path. Optionally transform the package data.

generator.package(pkg: Record<string, unknown>): this

Set the package data directly.

generator.readRepository(): this

Read and parse the repository URL from current git repository.

generator.repository(infoOrGitUrl: string | Partial<HostedGitInfo>): this

Set the repository info directly.

generator.options(options: Options): this

Set conventional-changelog options.

Name	Type	Default	Description
reset	boolean	false	Whether to reset the changelog or not.
append	boolean	false	Should the log be appended to existing data.
releaseCount	number	1	How many releases of changelog you want to generate. It counts from the upcoming release. Useful when you forgot to generate any previous changelog. Set to 0 to regenerate all.
outputUnreleased	boolean	true if a different version than last release is given. Otherwise false	If this value is true and context.version equals last release then context.version will be changed to 'Unreleased'.
transformCommit	(commit: Commit, params: Params) => Partial<Commit> | Promise<Partial<Commit> | null> | null		A transform function that applies after the parser and before the writer.
warn	function		Logger for warnings
debug	function		Logger for debug messages
fromatDate	(date: Date) => string		Custom date formatter function.

generator.context(context: Context): this

Set the writer context.

generator.tags(params: GetSemverTagsParams): this

Set params to get semver tags.

Name	Type	Default	Description
prefix	string | RegExp		Specify a prefix for the git tag that will be taken into account during the comparison.
skipUnstable	boolean	false	If set, unstable release tags will be skipped, e.g. x.x.x-rc.
clean	boolean	false	Clean version from prefix and trash.

If you want to take package-prefixed tags, for example lerna-style tags, you should use packagePrefix utility function:

import {
  ConventionalChangelog,
  packagePrefix
} from 'conventional-changelog'

const generator = new ConventionalChangelog()
  .readPackage()
  .loadPreset('angular')
  .tags({
    prefix: packagePrefix('foo-package')
  })

generator.commits(params: GetCommitsParams, parserOptions?: ParserStreamOptions): this

Set params to get commits.

• GetCommitsParams
• ParserStreamOptions

generator.writer(params: WriterOptions): this

Set writer options.

generator.write(includeDetails?: boolean): AsyncGenerator<string | Details<Commit>, void>

Generate changelog.

generator.writeStream(includeDetails?: boolean): Readable

Generate changelog stream.

License

MIT