This document explains the local release preparation workflow for git-merged-branches, including semantic versioning, changelog generation, and Git tag creation. The release process uses the commit-and-tag-version tool to automate version bumping, changelog updates, and tag creation based on conventional commit messages.
For information about the automated CI/CD pipeline that publishes releases to NPM, see 5.2 CI/CD Pipeline. For details about NPM publishing and provenance attestation, see 5.3 NPM Publishing.
The release process is a local operation executed by a developer with write access to the repository. It prepares the codebase for publication by updating version numbers, generating changelog entries, and creating Git tags that trigger downstream automation.
Sources: package.json44-45 .versionrc.cjs1-14
The project follows Semantic Versioning 2.0.0 and uses the commit-and-tag-version package to automate version bumps based on conventional commit messages.
The version increment type is determined automatically by analyzing commit messages since the last release:
| Commit Type | Version Impact | Example |
|---|---|---|
fix: | Patch (0.0.x) | Bug fixes |
feat: | Minor (0.x.0) | New features |
BREAKING CHANGE: footer | Major (x.0.0) | Breaking changes (e.g., Node.js version bump) |
Other types (chore:, docs:) | No version bump | Non-user-facing changes |
Git tags are created without a prefix, using only the version number. This is configured via the tagPrefix option in .versionrc.cjs:
This results in tags like 0.5.0 or 0.4.0, as seen in CHANGELOG.md5 and CHANGELOG.md14
Sources: .versionrc.cjs2 CHANGELOG.md5-14 package.json4
The release is initiated by running the npm script defined in package.json:
This executes the commit-and-tag-version command package.json49 which orchestrates the entire release preparation process.
Before any version changes are made, the .versionrc.cjs configuration defines a prerelease script that runs comprehensive quality checks:
This script performs three critical validation steps:
npm run lint:all):
lint:ts) package.json41lint:js) package.json42npm test):
npm run build):
tsdown package.json39dist/ package.json33If any of these steps fail, the release process is aborted, preventing the creation of a broken release.
Sources: .versionrc.cjs3-5 package.json39-45
Sources: .versionrc.cjs1-14 package.json4 CHANGELOG.md1-5
The .versionrc.cjs file includes custom writer options to handle edge cases in changelog generation. The finalizeContext function ensures that releases with no user-facing changes still produce a valid changelog entry:
This prevents empty changelog sections and provides clear communication when a release contains only internal changes (e.g., dependency updates). Examples of this can be seen in CHANGELOG.md28 CHANGELOG.md40 and CHANGELOG.md45
Sources: .versionrc.cjs6-13 CHANGELOG.md25-45
The CHANGELOG.md file is automatically maintained by parsing commit messages following the Conventional Commits specification.
Each release entry in the changelog includes:
| Section | Content | Source |
|---|---|---|
| Version header | Version number and release date | Parsed from Git tag and timestamp |
| Breaking changes | ⚠ BREAKING CHANGES section | Commits with BREAKING CHANGE: footer |
| Features | New capabilities added | Commits with feat: prefix |
| Bug fixes | Issues resolved | Commits with fix: prefix |
From CHANGELOG.md5-12:
This entry was generated from commits that modified the Node.js engine requirement package.json36 and updated build dependencies.
Sources: CHANGELOG.md1-111 package.json35-37
The version field in package.json is updated atomically during the release process:
This field is used by the NPM registry for package identification and by the CLI tools to display version information.
The process results in:
package.json package.json4CHANGELOG.md CHANGELOG.md5chore(release): X.Y.Z.X.Y.Z .versionrc.cjs2Sources: package.json4 CHANGELOG.md1-5 .versionrc.cjs1-14
npm run release.CHANGELOG.md and package.json.Sources: package.json45 .versionrc.cjs3-5
Refresh this wiki