yeaight7 Purpose
Confirm a release is correct, documented, validated, publishable, and reversible before any external write such as a tag push, package publish, or GitHub release.
When to Use
- Cutting a new version of a library, CLI, or service.
- Before
git tag,npm publish,gh release create, or equivalent. - When release steps span multiple systems or targets.
- When a release needs a go/no-go decision with rollback steps.
Inputs
- Intended version number or bump type
- Current package metadata
- Last release tag or compare base
- Changelog or release notes draft
- Publish target such as npm, PyPI, Docker, or GitHub Releases
Workflow
1. Version check
Read the current version from the relevant manifest and verify the target does not already exist:
npm view <pkg>@<version> version
pip index versions <pkg>
cargo search <pkg>
Confirm bump type:
- Breaking change -> major
- New user-facing capability -> minor
- Bug fix, catalog/doc correction, or asset polish -> patch
2. Compare range and change summary
git describe --tags --abbrev=0
git log <last-tag>..HEAD --oneline --no-merges
git diff --stat <last-tag>..HEAD
Flag breaking changes, release-note gaps, and user-visible assets that changed.
3. Metadata check
- README reflects current behavior.
- Manifest fields include description, license, homepage, repository, files, and publish config.
- No placeholder or TODO text appears in published metadata.
- Package contents match catalog paths.
For npm packages:
npm pack --dry-run
4. Validation gate
Run the full release suite for the project:
npm test
npm run build
python scripts/validate-skills.py
python scripts/validate-catalog.py
If a repository has a release preflight command, prefer it:
npm run release:check
5. Publish plan
Write exact commands before executing them:
git tag vX.Y.Z -m "Release vX.Y.Z"
git push origin vX.Y.Z
npm publish --access public
gh release create vX.Y.Z --verify-tag --title "vX.Y.Z" --notes-file <notes>
Wait for explicit approval before the first irreversible step.
6. Rollback plan
| Step | Rollback |
|---|---|
| local tag | git tag -d vX.Y.Z |
| pushed tag | git push origin :refs/tags/vX.Y.Z |
| npm publish | npm deprecate <pkg>@<ver> "released in error" |
| GitHub Release | gh release delete vX.Y.Z --yes |
Output
RELEASE READINESS: go / no-go
Version: X.Y.Z
Compare range: <last-tag>..HEAD
Changelog coverage: complete / gaps
Breaking changes: yes / no
Validation: <commands and result>
Publish plan: <exact commands>
Rollback plan: <exact commands>
Blockers: <none or list>
Verification
- Version does not already exist in the target registry.
- Compare range was reviewed.
- Changelog or release notes cover user-visible changes.
- Release validation commands exited 0.
- Package contents were checked when publishing a package.
- Rollback plan was written before tag or publish actions.
Failure Modes
- Releasing from a dirty working tree.
- Tagging a version already published.
- Trusting generated release notes without checking the compare range.
- Running publish commands before rollback is documented.
- Treating a GitHub Release as proof that package publishing succeeded.