Release Notes

Commit-driven changelog and release notes powered by semantic-release. package.json version is the source of truth—semantic-release updates it on each release; do not edit it manually.

Canonical release flow

1. Merge conventional-commit PRs into main.
2. CI passes, then the Release workflow runs semantic-release.
3. semantic-release computes the next semver version from commit history.
4. semantic-release updates package.json, docs/releases/CHANGELOG.md, and pnpm-lock.yaml, commits them, tags the release, and publishes a GitHub Release.
5. The docs site publishes the latest release notes content from this folder.

First release (no prior tags)

When there are no existing version tags, semantic-release analyzes all commits on main to compute the first version (e.g. 1.0.0 for a feat:).

Steps:

1. Ensure main has at least one release-worthy commit (feat:, fix:, or perf:).
2. CI must pass on main.
3. The Release workflow runs automatically after CI succeeds. Or trigger manually: Actions → Release → Run workflow.
4. semantic-release will update package.json, write CHANGELOG.md, commit, tag (e.g. v1.0.0), and create a GitHub Release.

Preview first: Run pnpm release:dry locally (with GH_TOKEN set) to see the computed version and notes before the workflow runs.

Merge and commit requirements

• Keep merge commits/squash titles in conventional commit format so semantic-release can analyze them.
• Prefer feat, fix, and perf for release-triggering changes.
• Use BREAKING CHANGE: footer (or type!:) for major releases.

Conventional commit to semver mapping

• feat: -> minor bump
• fix: / perf: -> patch bump
• BREAKING CHANGE footer or ! after type -> major bump
• other types (docs:, chore:, etc.) -> no release by default

Troubleshooting

No release was created

This usually means no new commits matched release-triggering types (feat, fix, perf, or breaking changes) since the last tag.

Run:

pnpm release:dry

and verify semantic-release logs show a computed release type.

Release workflow failed

Common causes:

1. Missing/invalid release token permissions.
2. Non-conventional merge commit title.
3. Protected branch settings blocking semantic-release git/changelog commit.

Recovery checklist:

1. Re-run pnpm release:dry locally with GH_TOKEN/GITHUB_TOKEN set.
2. Fix commit title format (or add a follow-up conventional commit) and merge again.
3. Verify workflow token can write contents and create releases.