release

When to Use

Use this skill when preparing, publishing, or verifying a gentle-pi release.

Hard Rules

• Do not publish gentle-pi to npm from a local machine.
• npm publishing MUST go through the GitHub Actions workflow .github/workflows/publish.yml so provenance, environment protection, and registry credentials are controlled by GitHub.
• Dispatch the trusted workflow definition from protected default main, never from a release tag. Its only caller input is the exact annotated version tag.
• Use a clean worktree for release commits. Do not package unrelated local files or scratch artifacts.
• Review outcomes are informational. Release delivery follows ordinary repository policy and must not be blocked, authorized, or rewritten by RDD.
• Never infer the release tag target from local HEAD; use the freshly fetched origin/main commit and the repository's normal release safeguards.
• Never skip package verification. The publish workflow runs verification again, but local validation should still pass before tagging.

Release Procedure

1. Inspect state

   git status --short
   git fetch origin main --tags
   git log --oneline --decorate --max-count=5 origin/main
   

2. Prepare the release commit

   • Apply only intended changes.
   • Bump package.json to the next semver version.
   • Keep lockfile changes out unless dependency resolution actually changed.

3. Verify locally

   pnpm test
   node scripts/verify-package-files.mjs
   npm pack --dry-run
   

   npm pack --dry-run verifies package contents and lifecycle scripts without entering a publish path.

4. Commit and push

   git add <intended-files>
   git commit -m "<type(scope): release-ready change>"
   git push origin HEAD:main
   git fetch origin main --tags
   

5. Create and verify the exact version tag

   version="$(node -p "require('./package.json').version")"
   tag="v${version}"
   release_sha="$(git rev-parse 'origin/main^{commit}')"
   
   test "$(git rev-parse 'HEAD^{commit}')" = "${release_sha}"
   test -z "$(git ls-remote --tags origin "refs/tags/${tag}")"
   
   git tag -a "${tag}" "${release_sha}" -m "gentle-pi ${tag}"
   test "$(git rev-parse "${tag}^{commit}")" = "${release_sha}"
   
   git fetch origin main
   test "$(git rev-parse 'origin/main^{commit}')" = "${release_sha}"
   git push origin "refs/tags/${tag}"
   
   git fetch --no-tags origin "refs/tags/${tag}"
   test "$(git rev-parse 'FETCH_HEAD^{commit}')" = "${release_sha}"
   
   gh release create "${tag}" \
     --repo Gentleman-Programming/gentle-pi \
     --verify-tag \
     --title "gentle-pi ${tag}" \
     --notes "<release notes>"