---
id: hatch3r-release
description: Cut a release with version bump, changelog, tagging, and deploy verification. Use when preparing a release, cutting a version, or deploying to production.
tags: [devops]
quality_charter: agents/shared/quality-charter.md
efficiency_patterns: agents/shared/efficiency-patterns.md
cache_friendly: true
---
> **Note:** Commands below use `npm` as an example. Substitute with your project's package manager (`yarn`, `pnpm`, `bun`) or build tool when your project uses a different package manager.

# Release Workflow

## Quick Start

```
Task Progress:
- [ ] Step 0: Detect ambiguity (P8 B1)
- [ ] Step 1: Determine version bump (major/minor/patch) based on changes
- [ ] Step 2: Generate changelog from merged PRs and commit history
- [ ] Step 3: Update version in package.json and any other version references
- [ ] Step 4: Verify quality gates (lint, typecheck, all tests)
- [ ] Step 5: Create git tag and platform release with changelog
- [ ] Step 6: Deploy and verify (staging first if applicable, then production)
- [ ] Step 7: Monitor post-deploy for errors/regressions
```

## Step 0 — Detect Ambiguity (P8 B1)

Before any work, scan the invocation for unresolved questions in scope, intent, acceptance criteria, target environment, or irreversibility. If any are found, ask the user via the platform-native question tool per `agents/shared/user-question-protocol.md`. Do not proceed under silent assumption. Default path, not an exception. Triggers for THIS skill: bump level (major vs minor vs patch), deploy authority (cut-only vs deploy-and-monitor), staging gate (required vs skipped), rollback policy (auto vs manual), and irreversible tag/publish operations (npm publish, GitHub release).

## Fan-out Discipline (P8 B2)

This skill delegates per task size:
- Tier 1 (trivial single-file): inline execution acceptable.
- Tier 2 (multi-file or multi-concern): spawn parallel sub-agents per concern via the Task tool.
- Tier 3 (multi-module / high-risk): one fresh sub-agent per independent module or gate; orchestrator integrates only.

Never under-fan-out to save tokens. Token cost is dominated by quality and completeness gains. Emit `sub_agents_spawned: { count, rationale }` in your output.

## Step 1: Determine Version Bump

- Review changes since last release: merged PRs/MRs, commit history.
- List merged PRs/MRs since last tag using the platform tools (check `platform` in `.hatch3r/hatch.json`):
  - **GitHub:** Use **GitHub MCP** (`search_issues`, PR search) or `gh pr list --state merged --base {defaultBranch}`
  - **Azure DevOps:** `az repos pr list --status completed --target-branch {defaultBranch}`
  - **GitLab:** `glab mr list --state merged --target-branch {defaultBranch}`
- Apply [Semantic Versioning](https://semver.org/):
  - **Major:** Breaking changes (API, data model, config)
  - **Minor:** New features, backward-compatible
  - **Patch:** Bug fixes, security patches, non-breaking improvements
- Check project release gates: no P0/P1 bugs open, E2E pass, performance budgets met.

## Step 2: Generate Changelog

- List merged PRs/MRs since last release (e.g., `git log v1.2.0..HEAD --oneline` or the platform's release/PR API).
- Group by category: Features, Bug Fixes, Security, Dependencies, Chore.
- Format each entry: `- description (#PR-number)` or `- description (commit hash)`.
- Include breaking changes section if major bump.
- Follow project changelog format (e.g., `CHANGELOG.md` or GitHub Release notes).

## Step 3: Update Version

- Update `version` in `package.json`.
- Update any other version references: `package-lock.json` (via `npm version`), docs, config files.
- Run `npm install` to refresh lockfile if needed.
- Commit with message: `chore(release): vX.Y.Z` or similar.

## Step 4: Verify Quality Gates

```bash
npm run lint && npm run typecheck && npm run test
npm run build
```

- All tests pass (unit, integration, E2E).
- Bundle size within budget (if defined).
- Security rules tests pass if rules changed.
- No TODO without linked issue.
- See project quality documentation for full pre-release gates.

## Step 5: Create Tag and Release

- Create annotated tag: `git tag -a vX.Y.Z -m "Release vX.Y.Z"`.
- Push tag: `git push origin vX.Y.Z`.
- Create the release using the platform CLI (check `platform` in `.hatch3r/hatch.json`):
  - **GitHub:** `gh release create vX.Y.Z --title "vX.Y.Z" --notes "{changelog}"` (or use **GitHub MCP** if available)
  - **Azure DevOps:** `az repos tag create vX.Y.Z` — attach release notes as a wiki page or work item, and upload build artifacts via Azure Artifacts
  - **GitLab:** `glab release create vX.Y.Z --name "vX.Y.Z" --notes "{changelog}"`
- Attach build artifacts if applicable.

## Step 6: Deploy and Verify

- Deploy to staging first (if applicable). Run smoke tests.
- Deploy to production (project-specific pipeline).
- Verify: health check, key flows.
- Document deploy method and environment in project docs if not already.

## Step 7: Monitor Post-Deploy

- Monitor error rate (target per project SLO).
- Monitor function/API error rate.
- Check for startup time regression.
- Watch user-reported issues for first 24h.
- If errors spike: rollback and investigate.

## Pre-Release Support

Version formats: alpha (`x.y.z-alpha.N`), beta (`x.y.z-beta.N`), release candidate (`x.y.z-rc.N`). Workflow:

1. Tag pre-release (e.g., `v1.2.0-beta.1`).
2. Publish to npm with `--tag` (`npm publish --tag beta`).
3. Smoke-test against the pre-release package.
4. Promote: publish stable without pre-release suffix.
5. Deprecate pre-release versions after stable release.

npm distribution tags: `latest` (stable), `beta`, `next` (RCs), `alpha`. GitHub releases for pre-releases use `--prerelease`.

## CHANGELOG.md Format

Follow Keep a Changelog:
- `### Added` — new features
- `### Changed` — changes to existing functionality
- `### Deprecated` — soon-to-be removed
- `### Removed` — removed features
- `### Fixed` — bug fixes
- `### Security` — vulnerability fixes

Entries grouped under `## [x.y.z] - YYYY-MM-DD`. Generate entry as part of the release commit; stage `CHANGELOG.md` alongside `package.json`. If `CHANGELOG.md` does not exist, create it with the standard header pointing to keepachangelog.com and semver.org.

## Rollback Procedure

If a release introduces critical issues:

- **npm:** `npm deprecate package@version "Critical issue — use version X instead"`. Within 72h, `npm unpublish package@version` is permitted (only inside npm's unpublish window). Publish a hotfix as a new patch release.
- **Git:** create a revert commit on the default branch, tag a new patch version, push to trigger the release workflow.
- **Communication:** update CHANGELOG with rollback notice, open a post-mortem issue, notify users via release notes/discussions.
- Always create a tracking issue documenting the incident. Never auto-rollback or auto-unpublish without explicit user confirmation; prefer deprecation over unpublish.

## Error Handling

- **Quality gates fail during release preparation**: Do not proceed with the release. Fix the failing gate (test failures, lint errors, type errors), re-run all gates, and restart the release process.
- **Git tag already exists for the target version**: Check whether the existing tag points to the correct commit. If it was created in error, delete and recreate it. If it was a previous release attempt, bump the version and start over.
- **Post-deploy monitoring detects regressions**: Execute the rollback plan immediately. Document the regression in a post-mortem issue and block the next release until the regression is fixed.

## Definition of Done

- [ ] Version bumped in package.json
- [ ] Changelog generated and included in release
- [ ] Git tag created and pushed
- [ ] Release published with changelog (GitHub Release / ADO wiki + tag / GitLab Release)
- [ ] Deployed to production and verified
- [ ] Post-deploy monitoring completed (no critical regressions)
- [ ] All release gates satisfied
