Skip to content

docs: add RELEASING.md - #16

Merged
zanjonke merged 1 commit into
mainfrom
docs/releasing
Aug 7, 2026
Merged

docs: add RELEASING.md#16
zanjonke merged 1 commit into
mainfrom
docs/releasing

Conversation

@zanjonke

@zanjonke zanjonke commented Aug 7, 2026

Copy link
Copy Markdown
Collaborator

Writes down the release procedure now that it's been proven end to end with v1.0.20.

Contents

  • The version lives in the tag — why package.json on main says 1.0.19 while npm serves 1.0.20, and why that's deliberate rather than drift to be fixed.
  • Cutting a release — the GitHub Release form fields and the gh release create equivalent.
  • What the workflow does — each step and guard, plus the OIDC/no-token model.
  • Pre-releases — the next dist-tag.
  • Release notes — the three-section convention, and the fact that editing notes fires release: edited so it never re-triggers a publish.
  • Releasing without Actionsscripts/deploy.sh, npm login, .env.release.
  • Prerequisites — trusted publisher, the one secret, branch protection, and the warning that renaming publish.yml breaks publishing until npmjs.com is updated.
  • Troubleshooting — everything that actually went wrong while setting this up: already-published versions, non-semver tags, re-runs replaying the old workflow file, and runs wedged in queued during an incident.

Also

A one-line pointer added to CLAUDE.md and AGENTS.md (kept in sync), so the version-lives-in-the-tag rule is visible to anyone reading the repo guidance.

@zanjonke
zanjonke merged commit 5d72c26 into main Aug 7, 2026
3 checks passed
@zanjonke
zanjonke deleted the docs/releasing branch August 7, 2026 07:19
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant