A good RELEASING.md names who can release, the exact steps, the checks to run first, how to verify the result and what to do if something goes wrong. One page is enough. Its security value is that releases stop depending on one person's memory.
Why write it down
Release steps live in a maintainer's head until that person is ill, busy or gone. A written runbook lets a second person ship a fix, and makes a handover or a compromise response faster. It also gives a reviewer something to compare against when a workflow changes.
Template
# Releasing
Who can release: names or team, and who approves
Where releases happen: the workflow file name, never a laptop
Before you start
- main is green and reviewed
- npm pack --dry-run (or your build tool's equivalent) shows only expected files
- CHANGELOG updated, security fixes called out
Release
- Create and push the version tag
- Approve the release environment if prompted
After release
- Verify checksum, signature identity and attestation
- Install the new version in a clean project
- Post the release note
If it goes wrong
- Deprecate or yank, do not rely on deleting
- Revoke tokens, review owners
- Publish an advisory
Section by section
| Section | Why it matters |
|---|---|
| Who can release | Makes access reviewable. See who can publish your package |
| Where releases happen | Pins the process to one workflow you can protect |
| Pre checks | Catches stray files and unreviewed changes. See check what you are about to publish |
| Verification | Proves your instructions work for users. See verify your own release |
| Rollback | Registries differ on removal. See unpublish, yank, deprecate compared |
Include the emergency path
Add a short section for the day a token leaks or an account is taken over: who to contact, what to revoke, how to warn users. Link to your npm package was compromised, a runbook or your own equivalent. Keep recovery codes and backups noted, but never store the codes in the repository. See maintainer account recovery codes and backups.
Keep it honest
Review the file whenever the pipeline changes. A runbook that describes last year's process is worse than none. Add it to your CODEOWNERS so changes get a second look, and note the last reviewed date inside.
Try it yourself
Click through it at your own pace, or open it full screen.
Click through and note how a finding appears after release. Your runbook should say who looks at that.
Safeguard offers continuous dependency monitoring and SBOM generation; try the free scan at gold.safeguard.sh/scan.
Quick check
Should RELEASING.md include secrets?
Never. List where credentials live and who holds them, but keep the values out of the repository.
Is one page really enough?
For a small project, yes. Link out for long procedures, and keep the main file short enough that people read it.
Last reviewed: 19 October 2026.
