@zokugun/bump-changelog
v0.2.0
Published
Update CHANGELOG.md automatically when you bump a version.
Maintainers
Readme
@zokugun/bump-changelog
bump-changelogpromotes the current Unreleased section to a versioned release heading, optionally keeps an empty Unreleased section, and can update Markdown link references.
Features
- Version Bumping: Inserts a new release section based on the updated package version.
- Unreleased Management: Keeps or removes the unreleased changes block depending on your config.
- Reference Handling: Adds and updates markdown link references for both old and new versions.
- Template Rendering: Uses custom templates to format release titles and dates dynamically.
- Heading Styles: Supports both ATX and Setext heading formats in the changelog document.
- Sorting Modes: Sorts references alphabetically, by version number, or leaves them unsorted.
- Location Types: Chooses between footnotes, headings, or sections for reference placement.
Installation
npm add --save-dev @zokugun/bump-changelogRequirements
- Node.js:
v18.20or higher - Modules: ECMAScript Modules (
ESM)
Quick Start
Add a version script to package.json. npm supplies the old and new versions to lifecycle scripts, so the command can run without arguments:
{
"scripts": {
"version": "bump-changelog"
}
}Run a version bump to update the changelog:
npm version patchAlternatively, pass both versions directly:
npx bump-changelog --old 1.2.3 --new 1.2.4The command expects a CHANGELOG.md with an Unreleased heading. By default, it uses ATX headings (## Unreleased) and adds the new release heading immediately after it, keeping the Unreleased section in place.
Configuration Example
Create .bumpchangelogrc.yml in your project root:
heading:
style: setext
release:
template: '[v{version}] | {date:YYYY-MM-DD}'
unreleased:
template: '[Unreleased]'
action: remove
reference:
release:
name: v{version}
link: https://github.com/owner/repo/releases/tag/v{version}
unreleased:
link: https://github.com/owner/repo/compare/v{version}...HEADThis configuration promotes the Unreleased heading to a versioned heading and updates the reference links. Set unreleased.action to retain to keep the Unreleased section and insert the release heading below it.
CLI
bump-changelog [options]| Option | Description |
| --------------------- | ------------------------------------------------ |
| -n, --new <version> | New version. Defaults to npm_new_version. |
| -o, --old <version> | Previous version. Defaults to npm_old_version. |
| -v, --version | Print the installed version. |
Both old and new versions are required. If the npm environment variables are not available, provide both options.
Configuration
Configuration files are optional. The tool checks .bumpchangelogrc{.yml,.yaml,.json,} from the project root.
The defaults are:
| Key | Default | Description |
| ------------------------------------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| heading.style | atx | Release heading style: atx (## Title) or setext (underlined title). |
| heading.separator.top | blankline | Blank line before inserted content, or none. |
| heading.separator.bottom | blankline | Blank line after inserted content, or none. |
| release.template | {version} - {date:YYYY-MM-DD} | Format for the new release heading. |
| unreleased.action | retain | retain keeps the Unreleased heading; remove replaces it with the release heading. |
| unreleased.template | Unreleased | Text used to locate and render the Unreleased heading. |
| reference | disabled | Configure this to add or update Markdown references. |
| reference.location.by | footnote | Reference placement: footnote, heading, or section. |
| reference.location.position | after | For heading placement, references go after the Unreleased heading by default; before is also supported. |
| reference.location.separator.top | none for heading; blankline for section | Spacing before heading- or section-based references. |
| reference.location.separator.bottom | blankline | Spacing after heading- or section-based references. |
| reference.release.name | {version} | Label for a release reference. |
| reference.release.link | Required | Link template for release references. |
| reference.sort.mode | alpha-version | Sort references by label and version; alphabetical and none are also supported. |
| reference.sort.direction | { alpha: asc, version: desc } | Sort labels ascending and versions descending. |
| reference.unreleased.name | unreleased | Label for the Unreleased reference. |
| reference.unreleased.link | Required | Link template for the Unreleased reference. |
When reference is enabled, both link templates are required.
Template Variables
{version}: The new version. In reference names and links, it resolves to the version associated with that reference.{date:FORMAT}: Current date formatted with Day.js format tokens, such as{date:YYYY-MM-DD}.{git.branch},{git.commitId},{git.distance}: Values read from the current Git repository.
Contributions
Contributions are most welcome. Please:
- Open issues and feature requests under the repository discussions.
- Follow the
CONTRIBUTING.md.
Donations
Support this project by becoming a financial contributor.
License
Copyright © 2026-present Baptiste Augrain
Licensed under the MIT license.
