Contribution
Release procedure
Releases are derived from commit messages. Nobody bumps a version or pushes a tag by hand.
Commit messages
master is squash-merged, so the pull request title is the commit message. It follows
Conventional Commits: <type>: <what changed>.
| Type | Release |
|---|---|
feat | minor (1.11.3 → 1.12.0) |
fix, perf | patch (1.11.3 → 1.11.4) |
docs, refactor, test, build, ci, chore, style | none |
a ! after the type (feat!:) or a BREAKING CHANGE: footer | major |
A title in another shape (Add x, 1.12.0: add x) is not an error, it just does not release.
A breaking change releases a major version on its own, so it is only ever written on request. AI agents working in this repository ask first and never add the marker themselves.
What happens on a merge to master
semantic-release (.github/workflows/release.yaml,
.releaserc.json) reads the commits since the last tag. When one of them releases, it:
- bumps
package.jsonandpackage-lock.jsonand adds the section toCHANGELOG.md, in achore(release): x.y.z [skip ci]commit on master, - tags
vX.Y.Z, - starts the publish workflow (
.github/workflows/push.yaml) for the tag: it creates the GitHub release with the changelog section as notes and the binaries attached, publishes the Docker Hub image and publishes to npm. For a stable release it then regenerates the formula in the Homebrew tap from the binaries' checksums and pushes it to the tap'smain, - starts the website workflow (
.github/workflows/website.yaml) on master, which rebuilds hammerkit.dev. Its changelog page is generated fromCHANGELOG.md(website/scripts/changelog.mjs), so it lists the new release without further work. Releases before 1.12 have hand-written entries inwebsite/content/changelog, which win over a generated one for the same version.
Setup and recovery
mastermust accept pushes from the workflow (the release commit and the tag).- The Homebrew step needs the secret
HOMEBREW_TAP_TOKEN, a fine-grained token with Contents: write onno0dles/homebrew-hammerkitonly. Without it the step is skipped and the formula is updated by hand (hammerkit.rb.tmplin the tap lists the placeholders). - The repository's releases are immutable, so the release is created together with its binaries
and cannot be edited afterwards. If publishing fails before the release exists, fix the cause and
re-run it from the tag: Actions → publish → Run workflow, choosing the
vX.Y.Ztag as the ref. - A prerelease (
1.12.0-alpha.0) is still cut by hand withnpm version prerelease --preid alphaandgit push origin --follow-tags; the npm dist-tag follows the preid.