Releasing cafaye-ts

Releasing cafaye-ts

A tag is the release. Pushing vX.Y.Z runs .github/workflows/release.yml, which gates, packs, creates the GitHub Release, and publishes to the registry when it can. There is no other release path.

This shape is the fleet uniform: cafaye-rb and cafaye-py follow this same file. What is written here is what this repository actually built — nothing more.

Cutting a release

1. Move the Unreleased section of CHANGELOG.md to X.Y.Z and date it. The section is built from the repo’s actual history, never invented. Leave an empty ## [Unreleased] at the top for the permanent discipline.
2. Bump the manifest, lockfile included, without creating a tag: npm version X.Y.Z --no-git-tag-version (updates package.json and package-lock.json together — npm ci fails when the two disagree, so a hand-edit of one file is half a bump).
3. Commit both, merge, then cut and push the tag: git tag -a vX.Y.Z -m "cafaye-ts X.Y.Z" && git push origin vX.Y.Z The tag and the manifest must agree — the workflow checks v0.1.0 against 0.1.0 and stops the release if they differ. Never create the tag before the bump commit is merged; never move a tag after pushing it.

What the workflow does

• Checks out this repo plus the six fleet services (the drift test verifies provenance against sibling checkouts and skips without them — a release must not be a vacuous green).
• Runs bin/prime: frozen install, typecheck, the full suite. A release that skips the gate is not a release.
• Runs npm pack. The tarball is the artifact.
• Reads the release notes out of CHANGELOG.md — the ## [X.Y.Z] section, nothing else. The notes ARE the changelog section, not a generated commit dump. A missing section stops the release.
• Creates the GitHub Release titled vX.Y.Z with the tarball attached, using the runner’s gh and the job’s contents: write permission.
• Publishes to the npm registry only when the credential exists (below). Node is pinned to 22.19.0 — the same pin as mise.toml and ci.yml — never @latest.

Registry publishing: the one credential

The account currently has no npm token configured, so releases ship as GitHub Releases with the tarball attached, and the publish step logs that it skipped. That is the designed behaviour, not a failure. To enable registry publishing, add an npm access token with publish permission on cafaye-ts as the repository secret NPM_TOKEN (repo Settings → Secrets → Actions). Nothing else changes: the next tag run publishes with no workflow edit.

Two things deliberately not wired yet: --provenance (needs id-token: write plus trusted publishing configured on the npm package — add the permission and the flag together, in one commit, when the organisation owner sets that up) and a scoped @cafaye/* name (the name question is still open — see the DECISION NEEDED in cafaye.yml).

Semver here

Pre-1.0: 0.x.y releases may break the API on a minor bump, and every break is listed in the changelog with the commit that caused it. 0.1.0 (2026-10-15) is the first release; package.json read 0.0.0 before it, and no tag had ever been cut.