# Release Cycle

> Release Cycle Lifecycle

- Skill: `jorelcb/release-cycle` (Agent Skill)
- Install (CLI): `npx skillmds@latest add jorelcb/release-cycle`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jorelcb/release-cycle/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: jorelcb (https://skillmd.com/u/jorelcb)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jorelcb/release-cycle

---

# Release Cycle Lifecycle

Take a codebase through a traceable, reversible release: confirm readiness, choose the version, update references, generate the changelog, commit, tag, push, deploy, and verify. This keeps every release documented and recoverable.

## When to use

- Cutting a new release once features and fixes are merged
- Bumping the version and producing a changelog
- Tagging and pushing a release, then triggering deployment
- Auditing whether a release followed a safe, reversible sequence

As a Claude Code skill, this may declare `allowed-tools` so safe local steps (editing version files, generating the changelog, creating the release commit) run without re-prompting. Keep irreversible, public steps — pushing a tag, publishing a release, deploying — interactive and explicitly confirmed.

## Process

### 1. Verify release readiness

Before anything else:

- All planned features and fixes are merged
- The test suite passes on the release branch
- No open blockers or critical issues remain
- You have reviewed the full set of changes since the last release

### 2. Determine the version number

Follow Semantic Versioning, driven by the commits since the last release:

- **MAJOR** (X.0.0): breaking changes to public APIs or contracts — any `feat!:` or `BREAKING CHANGE:`
- **MINOR** (x.Y.0): new backward-compatible features — any `feat:`
- **PATCH** (x.y.Z): backward-compatible fixes only — `fix:`, `docs:`, `chore:`

### 3. Update version references

Update every place the version appears:

- The version file or constant (`version.go`, `package.json`, `.version`, etc.)
- Documentation badges
- Any configuration that pins the version

### 4. Generate the changelog

Create or update the changelog in the project's format (CHANGELOG.md, GitHub releases, etc.):

- Group changes by type: Breaking Changes, Features, Bug Fixes, Other
- Place breaking changes prominently at the top
- Include commit references for traceability

### 5. Create the release commit

Make a single commit holding only version-related changes:

- Message: `chore: bump version to vX.Y.Z`
- Include the version-file edits and changelog updates
- Do not include any code changes in this commit

### 6. Create the git tag

Tag the release commit:

- Tag format `vX.Y.Z`, matching the project's convention
- Use an annotated tag carrying the changelog summary
- Pushing a tag is irreversible and public — confirm before pushing

### 7. Push the release

Push the release commit, then the tag, and verify both arrive at origin. Always push the commit before the tag so the tag never points at a commit that is not yet on the remote.

### 8. Trigger deployment

When the project has a CI/CD pipeline:

- Confirm CI/CD picks up the new tag
- Monitor the pipeline for failures
- Validate the deployment in the target environment

### 9. Publish release notes

When using GitHub/GitLab releases:

- Target the tag as the release
- Use the changelog entries as the release notes
- Attach relevant artifacts (binaries, packages)
- Mark as pre-release if appropriate

### 10. Verify the release is healthy

- The deployed version matches the release
- Smoke tests pass against the deployed environment
- Error rates and performance metrics show no anomalies
- Package-registry publication succeeded, if applicable

## Anti-patterns

- Releasing without running the full test suite
- Skipping the changelog, making later regression hunts harder
- Tagging before the commit is pushed, risking a tag/commit mismatch
- Including code changes in the version-bump commit
- Walking away after deploy instead of monitoring for early failures
- Drifting from a consistent semver tag format

## Verification

Before declaring the release done:

- [ ] Release branch is green and free of blockers
- [ ] Version bump matches the SemVer impact of the merged commits
- [ ] All version references and badges are updated
- [ ] Changelog is generated with breaking changes surfaced first
- [ ] Version bump commit contains no code changes
- [ ] Annotated tag was pushed only after the commit reached origin
- [ ] Deployment was monitored and the deployed version verified