How to cut a release

Purpose #

Step-by-step release recipe via Changesets, with the alpha (pre-1.0) and latest (v1.0+) variants and the provenance flag.

Big Picture #

Releases go via Changesets (ADR-0004 §4). Pre-1.0 uses the alpha dist-tag and latest stays unset. v1.0 GA migrates latest and turns on npm provenance for every @aidokit/* package.

Source of truth on the publish pipeline: contributing/release-checklist.md, diagrams/release-flow.md, .docs/docs/architecture/decisions/0004-distribution.md §Implementation notes.

Pre-release verification #

Before cutting:

pnpm install --frozen-lockfile
pnpm lint
pnpm typecheck
pnpm build
pnpm test
pnpm --filter '@aidokit/adapter-*' test test/conformance.test.ts
pnpm --filter '@aidokit/stack-pack-*' test test/conformance.test.ts

Run the dogfood byte-compare (see how-to-run-tests-and-byte-compare.md).

Confirm:

• All pending .changeset/*.md files reviewed and merged.
• Each affected package's package.json declares "license": "Apache-2.0" and "engines": { "node": ">=20.0.0" }.
• Each affected package's files allowlist is correct (dist + README + LICENSE + NOTICE + CHANGELOG).

Pre-1.0 release (alpha dist-tag) #

pnpm changeset version                # consumes .changeset/*.md → bumps package.json + per-package CHANGELOG
pnpm install --frozen-lockfile=false  # refresh lockfile
pnpm build
pnpm test
pnpm changeset publish --tag alpha    # publishes only changed packages

latest is intentionally not updated pre-1.0 so npx aidokit init does not silently grab a pre-release. Users opt in via npx aidokit@alpha init.

v1.0+ release (latest dist-tag, with provenance) #

pnpm changeset version
pnpm install --frozen-lockfile=false
pnpm build
pnpm test
NPM_CONFIG_PROVENANCE=true \
  pnpm changeset publish              # defaults to 'latest'
# Equivalent: npm publish --provenance --access public per package

Provenance requires GitHub Actions OIDC (or equivalent). The CI workflow snippet in ADR-0004 §Implementation notes sets id-token: write and NPM_CONFIG_PROVENANCE: true.

Verify after publish:

npm view aidokit dist-tags
npm view @aidokit/core dist-tags
npm audit signatures

Optional v0.5 beta dist-tag #

If a wider beta is appropriate, use --tag beta:

pnpm changeset publish --tag beta

This is optional per ADR-0004 §3 — alpha remains the default pre-1.0 stream.

Post-publish #

1. Tag the release commit in git:

git tag -a v0.5.0 -m "v0.5.0"     # or whatever version
git push --tags

2. Open a GitHub Release with the per-package CHANGELOG excerpts.
3. Update the wiki's CHANGELOG.md [Unreleased] → versioned heading.
4. Smoke test:

npx aidokit@<version> init --adapter claude-code --stack node-ts --yes

In a fresh temp dir.

Common pitfalls #

• Skipping pnpm install after changeset version. The new versions need to land in the workspace lockfile.
• Forgetting --provenance at v1.0. Required (ADR-0004 §5); reviewers run npm audit signatures.
• Promoting latest pre-1.0. Breaks the documented dist-tag policy and surprises users.
• Publishing from a local machine pre-v1.0 without coordinating — fine for early alpha but make sure the CI publish job is also disabled to avoid double publish.
• Mixing dist-tags. pnpm changeset publish --tag alpha --tag latest is not supported; pick one.

Related Pages #

• ../concepts/release-and-distribution.md
• ../diagrams/release-flow.md
• ../contributing/release-checklist.md
• ADR-0004