hammerkit
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>.

TypeRelease
featminor (1.11.3 → 1.12.0)
fix, perfpatch (1.11.3 → 1.11.4)
docs, refactor, test, build, ci, chore, stylenone
a ! after the type (feat!:) or a BREAKING CHANGE: footermajor

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:

  1. bumps package.json and package-lock.json and adds the section to CHANGELOG.md, in a chore(release): x.y.z [skip ci] commit on master,
  2. tags vX.Y.Z,
  3. 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's main,
  4. starts the website workflow (.github/workflows/website.yaml) on master, which rebuilds hammerkit.dev. Its changelog page is generated from CHANGELOG.md (website/scripts/changelog.mjs), so it lists the new release without further work. Releases before 1.12 have hand-written entries in website/content/changelog, which win over a generated one for the same version.

Setup and recovery

  • master must 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 on no0dles/homebrew-hammerkit only. Without it the step is skipped and the formula is updated by hand (hammerkit.rb.tmpl in 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.Z tag as the ref.
  • A prerelease (1.12.0-alpha.0) is still cut by hand with npm version prerelease --preid alpha and git push origin --follow-tags; the npm dist-tag follows the preid.

On this page