Release process

Prerequisites:

• git-cliff in PATH (scoop install git-cliff on Windows)

• Git Bash or another bash shell (bash ships with Git for Windows)

• Clean working tree on main or master

# Preview the next version and changelog
npm run release -- --dry-run patch

# Bump version, update CHANGELOG.md, commit, tag, and push to origin
# (pushing the tag starts the GitHub Actions Release workflow)
npm run release -- patch   # or minor | major

If you only push a version bump to main without a tag, the Tag version workflow creates vX.Y.Z automatically when that tag is missing.

Release commits use the message chore(release): vX.Y.Z and are excluded from future changelogs. Pass --no-test to skip the pre-release test run, --no-push to create commit+tag locally only.

The Release workflow builds installers for Windows, macOS, and Linux, publishes a GitHub Release, and deploys this documentation to GitHub Pages. Signing and notarization secrets are documented in CI secrets for release builds.

GitHub Pages uses the github-pages environment. That environment must allow deployments from the default branch (main) and from version tags matching v* (Settings → Environments → github-pages → Deployment branches and tags). Without the v* tag rule, tag-triggered Release runs fail Pages deploy with “Tag is not allowed to deploy…”.