@zumerbox/changelog

A simple tool for generating changelogs for your projects, on top of auto-changelog.

Installation

npm install @zumerbox/changelog --save-dev

Usage

npx @zumerbox/changelog

Run after tagging a new version (typically as a postbump script). The tool will either insert a new section at the top of CHANGELOG.md or update the section for the current version if it already exists.

Behavior

• Past releases are never touched. Only the section for the latest tag is regenerated. Anything you have above older releases stays byte-for-byte.
• First run (no CHANGELOG.md yet): generates the full file from git history.
• Subsequent runs: generates only the section for the latest tag (git describe --tags --abbrev=0) and either prepends it or replaces the existing entry for that version.
• Entries are grouped by conventional-commit type, in this order: Breaking changes, Features, Fixes, Performance, Refactoring, Docs, Tests, Chores (chore, build, ci, style, revert), Other. The type(scope): prefix is removed and the scope is kept in bold: fix(stream): keep ... becomes **stream:** keep .... A ! after the type or a BREAKING CHANGE note puts the entry under Breaking changes.
• Noise commits are filtered: commit subjects matching ^Bumped( \S+)? version, ^Create LICENSE, ^Update README, ^Update LICENSE, ^Update CHANGELOG are excluded from the output.
• A file with its own title keeps it. When CHANGELOG.md starts with a # Title instead of the tool's header, the new entry goes below the title and its heading copies the level and the v prefix of the entries already there (## 1.2.3 stays ## 1.2.3).

Any extra arguments you pass are forwarded to auto-changelog as-is, except --dry-run, which prints the section that would be written and leaves CHANGELOG.md alone.

Monorepos

Each package gets its own changelog, from its own commits:

• At the repo root (a package.json with workspaces), commits that touch only a workspace package are left to that package's changelog. Lockfiles (package-lock.json, yarn.lock, pnpm-lock.yaml) do not count as root files, since every workspace bump moves them.
• Inside a workspace package (run from its folder), only commits that touch that folder count, the repo's tags are ignored, and the entry covers everything since the commit that last changed the package's package.json version. The entry is titled with the package's current version, so run it right after bumping, before committing the bump.

Migration from 1.x

1.x regenerated the whole file on every run, which meant manual edits to past sections were lost and reformatting from new auto-changelog versions silently rewrote published entries. 2.0 makes past entries immutable: only the latest release section is touched. Custom edits to past sections are now safe.

Credits

Powered by auto-changelog.