# Release Hygiene

> Prepares and maintains a public open-source repository: version tags aligned with package versions, GitHub Releases with meaningful notes, Dependabot with a PR decision policy, issue templates, and discovery metadata (topics, badges). Use when publishing a new project, cutting a release, or cleaning up a repo before promoting it.

- Skill: `zhengqiuyang/release-hygiene` (Agent Skill)
- Install (CLI): `npx skillmds@latest add zhengqiuyang/release-hygiene`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zhengqiuyang/release-hygiene/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- License: MIT
- Author: zhengqiuyang (https://skillmd.com/u/zhengqiuyang)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/zhengqiuyang/release-hygiene

---


# Release Hygiene

The gap between "pushed code" and "presentable project" is about 40 minutes
of hygiene. This is the checklist.

## First release

1. **Version pinning**: tag must equal `package.json` version. Note: `gh
   release create v0.1.0` creates the remote tag itself at the default
   branch HEAD — fetch tags locally afterwards (`git fetch --tags`) to keep
   local/remote aligned.
2. **Release notes**: one paragraph of what it is + the gap it fills, test/
   CI summary, link to docs. Never just "--generate-notes" commit spam.
3. **Discovery surface**: repo topics (`gh repo edit --add-topic ...` — pick
   the phrases your audience actually browses), description, README badge.
4. **Issue templates**: bug (command + observed + expected + environment) and
   feature (problem → wanted behavior → why existing tools don't cover).
5. **Dependabot** for both `npm` and `github-actions` ecosystems, 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.