release-management

# Release Management Automate releases with `gh release`, semantic versioning, and changelog generation. > **CC ≥ 2.1.118 (M122):** `claude plugin tag <version>` validates the plugin manifest hierarchy (marketplace.json, plugin.json, package.json, version.txt) before tagging. Runs `--dry-run` in CI before release-please opens its release PR; catches manifest drift early. See `src/skills/chain-patterns/references/plugin-tag.md`. ## CRITICAL: Task Management is MANDATORY (CC 2.1.16) **BEFORE doing ANYTHING else, create tasks to track progress:** ```python # 1. Create main task IMMEDIATELY TaskCreate( subject="Release: {version}", description="Creating release with semantic versioning and changelog", activeForm="Releasing {version}" ) # 2. Create subtasks for each release phase TaskCreate(subject="Version & changelog", activeForm="Determining version and generating changelog") TaskCreate(subject="Create release", activeForm="Creating GitHub release") TaskCreate(subject="Verify & announce", activeForm="Verifying release and announcing") # 3. Set dependencies for sequential phases TaskUpdate(taskId="3", addBlockedBy=["2"]) TaskUpdate(taskId="4", addBlockedBy=["3"]) # 4. Update status as you progress TaskUpdate(taskId="2", status="in_progress") # When starting TaskUpdate(taskId="2", status="completed") # When done ``` ## Quick Reference ### Create Release ```bash # Auto-generate notes from PRs gh release create v1.2.0 --generate-notes # With custom title gh release create v1.2.0 --title "Version 1.2.0: Performance Update" --generate-notes # Draft release (review before publishing) gh release create v1.2.0 --draft --generate-notes # Pre-release (beta, rc) gh release create v1.2.0-beta.1 --prerelease --generate-notes # With custom notes gh release create v1.2.0 --notes "## Highlights - New auth system - 50% faster search" # From notes file gh release create v1.2.0 --notes-file RELEASE_NOTES.md ``` ### List & View Releases ```bash # List all releases gh release list # View specific release gh release view v1.2.0 # View in browser gh release view v1.2.0 --web # JSON output gh release list --json tagName,publishedAt,isPrerelease ``` ### Verify Releases (gh CLI 2.86.0+) ```bash # Verify release attestation (sigstore) gh release verify v1.2.0 # Verify specific asset gh release verify-asset v1.2.0 ./dist/app.zip # Verify with custom trust policy gh release verify v1.2.0 --owner myorg ``` ### Manage Releases ```bash # Edit release gh release edit v1.2.0 --title "New Title" --notes "Updated notes" # Delete release gh release delete v1.2.0 # Upload assets gh release upload v1.2.0 ./dist/app.zip ./dist/app.tar.gz ``` --- ## Semantic Versioning ```text MAJOR.MINOR.PATCH │ │ │ │ │ └── Bug fixes (backwards compatible) │ └──────── New features (backwards compatible) └────────────── Breaking changes Examples: 1.0.0 → 1.0.1 (patch: bug fix) 1.0.1 → 1.1.0 (minor: new feature) 1.1.0 → 2.0.0 (major: breaking change) Pre-release: 2.0.0-alpha.1 (early testing) 2.0.0-beta.1 (feature complete) 2.0.0-rc.1 (release candidate) ``` --- ## Release Workflows Standard and hotfix release procedures using git tags and `gh release`. Load Read("references/release-workflows.md") for step-by-step standard and hotfix release workflows. --- ## Changelog Generation Auto-generated from PRs, custom `.github/release.yml` templates, and manual CHANGELOG.md format. Load Read("references/changelog-generation.md") for changelog template examples and Keep-a-Changelog format. --- ## Release Automation & Checklist GitHub Actions workflow for tag-triggered releases, version bumping script, and pre/post-release checklist. Load Read("references/release-automation.md") for CI workflow, bump script, and release checklist. --- ## Best Practices 1. **Use semantic versioning** - Communicate change impact 2. **Draft releases first** - Review notes before publishing 3. **Generate notes from PRs** - Accurate, automatic history 4. **Close milestone on release** - Track completion 5. **Tag main only** - Never tag feature branches 6. **Announce breaking changes** - Prominent in release notes ## Related Skills - `ork:github-operations`: Milestones, issues, and CLI reference - `ork:github-operations`: Branch management and git operations ## References Load on demand with `Read("references/<file>")`: | File | Content | |------|---------| | `semver.md` | Semantic versioning rules and decision tree | | `release-workflows.md` | Standard and hotfix release procedures | | `changelog-generation.md` | Auto-generated, template, and manual changelog formats | | `release-automation.md` | GitHub Actions workflow, bump script, and checklist |