zhengqiuyang Release Hygiene
The gap between "pushed code" and "presentable project" is about 40 minutes of hygiene. This is the checklist.
First release
- Version pinning: tag must equal
package.jsonversion. Note:gh release create v0.1.0creates the remote tag itself at the default branch HEAD — fetch tags locally afterwards (git fetch --tags) to keep local/remote aligned. - Release notes: one paragraph of what it is + the gap it fills, test/ CI summary, link to docs. Never just "--generate-notes" commit spam.
- Discovery surface: repo topics (
gh repo edit --add-topic ...— pick the phrases your audience actually browses), description, README badge. - Issue templates: bug (command + observed + expected + environment) and feature (problem → wanted behavior → why existing tools don't cover).
- Dependabot for both
npmandgithub-actionsecosystems, weekly.
PR decision policy (Dependabot will come)
Dependabot opens PRs within minutes of activation — expect 4 per repo. Decide by class, not one by one:
- Patch/minor bumps: check CI on the PR branch, merge if green.
- Major bumps (frameworks, actions major versions): they break builds — that is CI correctly doing its job. Never auto-merge; batch them for a dedicated migration session.
- Actions bumps (
checkout@4→7): major-version workflows changes; verify the workflow still triggers after upgrade.
Per-release ritual
# bump version in package.json, commit
git tag vX.Y.Z && git push origin main --tags
gh release create vX.Y.Z --title "name vX.Y.Z" --notes "..."
Notes should answer: what changed, what breaks, what's next. If the project has a changelog tool, generate from it — commit-linked and deterministic.
npm publishing checklist (when applicable)
files field curated (ship dist + docs, not tests), prepublishOnly =
build + test, engines declared, npm pack --dry-run reviewed (size and
file list) before npm publish. Versions are immutable — 72h unpublish
window, then deprecate-only.