release-procedures

Version management, release verification, and deployment procedures for software releases. Includes semver guidance, version consistency checks, and platform-specific constraints.

⭐126stars🔀14forks📁View on GitHub🕐Updated Dec 27, 2025⬇️1downloads

When & Why to Use This Skill

This Claude skill provides a comprehensive framework for software release management, focusing on systematic versioning, deployment verification, and cross-platform consistency. It streamlines the transition from development to production by enforcing Semantic Versioning (SemVer) standards, automating version checks across multiple configuration files, and providing platform-specific deployment guides for npm, VS Code extensions, and Python packages. By integrating structured workflows and rollback procedures, it minimizes human error and ensures high-quality software delivery.

Use Cases

  • 1. Automated Version Management: Automatically calculate and apply MAJOR, MINOR, or PATCH updates based on feature changes or bug fixes to maintain strict SemVer compliance.
  • 2. Pre-Release Verification: Perform automated checks to ensure version consistency between package.json, CHANGELOG.md, and README.md before finalizing a release.
  • 3. Multi-Platform Deployment: Execute standardized deployment procedures tailored for specific ecosystems, including VS Code Marketplace constraints and PyPI PEP 440 compliance.
  • 4. Collaborative Release Workflows: Coordinate a two-stage release process where DevOps agents manage local commits and UAT approvals before the final public push.
  • 5. Incident Recovery and Rollbacks: Follow structured emergency procedures to unpublish failed releases and revert Git tags, maintaining repository integrity during deployment failures.
namerelease-procedures
descriptionVersion management, release verification, and deployment procedures for software releases. Includes semver guidance, version consistency checks, and platform-specific constraints.
licenseMIT
authorgroupzer0
version"1.0"

Release Procedures

Systematic approach to packaging and releasing software. Use this skill when:

  • DevOps prepares a release for deployment
  • Implementer updates version files during milestones
  • Planner specifies version bumps in plans

Release Workflow

┌─────────────────────────────────────────────────────────────────┐
│                    Two-Stage Release Flow                       │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  STAGE 1: Per-Plan (repeat for each plan in release)            │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │  1. QA Complete                                         │    │
│  │  2. UAT Approved                                        │    │
│  │  3. DevOps commits locally (NO PUSH)                    │    │
│  │  4. Update plan status: "Committed for vX.Y.Z"          │    │
│  │  5. Notify Roadmap of commit                            │    │
│  └─────────────────────────────────────────────────────────┘    │
│                                                                 │
│  STAGE 2: Per-Release (once all plans committed)                │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │  1. All plans for release committed                     │    │
│  │  2. User approves release                               │    │
│  │  3. Git tag, push, publish                              │    │
│  │  4. Update all plan statuses: "Released"                │    │
│  │  5. Hand off to Retrospective                           │    │
│  └─────────────────────────────────────────────────────────┘    │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Semantic Versioning (SemVer)

Version Format: MAJOR.MINOR.PATCH

Bump When Examples
MAJOR Breaking changes API signature change, removed feature
MINOR New features (backward compatible) New command, added option
PATCH Bug fixes (backward compatible) Fixed crash, corrected behavior

Pre-Release Versions

1.2.3-alpha.1    # Early development
1.2.3-beta.1     # Feature complete, testing
1.2.3-rc.1       # Release candidate

When to Bump

Change Type Version Rationale
Fix typo in docs PATCH No code change
Fix bug PATCH Backward compatible
Add new feature MINOR New capability
Deprecate feature MINOR Still works
Remove deprecated MAJOR Breaking
Change API contract MAJOR Breaking

Version Consistency Checklist

All version references must match before release:

File Field Example
package.json version "version": "1.2.3"
CHANGELOG.md Latest heading ## [1.2.3] - 2024-12-19
README.md Badge/install (if versioned) May be "latest"
Platform config Varies See platform-specific

Verification Command

# Extract and compare versions
PACKAGE_VERSION=$(jq -r .version package.json)
CHANGELOG_VERSION=$(grep -oP '## \[\K[0-9]+\.[0-9]+\.[0-9]+' CHANGELOG.md | head -1)

if [ "$PACKAGE_VERSION" != "$CHANGELOG_VERSION" ]; then
  echo "VERSION MISMATCH: package.json=$PACKAGE_VERSION, CHANGELOG=$CHANGELOG_VERSION"
  exit 1
fi

Platform-Specific Constraints

VS Code Extensions

Constraint Requirement
Version format 3-part semver only (X.Y.Z)
Pre-release Use odd minor version (e.g., 1.1.0)
Engine Specify minimum VS Code version
{
  "version": "1.2.3",
  "engines": { "vscode": "^1.80.0" }
}

npm Packages

Constraint Requirement
Version Standard semver
Pre-release -alpha.1, -beta.1 allowed
Deprecation Use npm deprecate

Python Packages (PyPI)

Constraint Requirement
Version PEP 440 compliant
Pre-release a1, b1, rc1 suffixes
Location setup.py, pyproject.toml, or __version__

CHANGELOG Format

Follow Keep a Changelog:

# Changelog

All notable changes to this project will be documented in this file.

## [Unreleased]

## [1.2.3] - 2024-12-19

### Added
- New feature description

### Changed
- Modified behavior description

### Fixed
- Bug fix description

### Deprecated
- Feature to be removed

### Removed
- Removed feature

### Security
- Security fix description

Categories Order

  1. Added (new features)
  2. Changed (changes to existing)
  3. Deprecated (soon to be removed)
  4. Removed (now removed)
  5. Fixed (bug fixes)
  6. Security (vulnerability fixes)

Pre-Release Verification

Mandatory Checks

Check Command/Action Fail Response
UAT Status Read agent-output/uat/ STOP if not "APPROVED FOR RELEASE"
QA Status Read agent-output/qa/ STOP if not "QA Complete"
Version Match Compare all version files STOP and fix
Tests Pass Run test suite STOP and fix
Clean Workspace git status Commit or stash
No Debug Check for debug flags Remove before release

Pre-Commit Cleanup

# Ensure no debug artifacts
grep -r "console.log" src/ --include="*.ts" && exit 1
grep -r "debugger" src/ --include="*.ts" && exit 1
grep -r "TODO: remove" src/ && exit 1

Release Execution

Git Tagging

# Create annotated tag
git tag -a v1.2.3 -m "Release v1.2.3"

# Push tag
git push origin v1.2.3

Publication Commands

Platform Command
VS Code vsce publish
npm npm publish
PyPI twine upload dist/*
GitHub gh release create v1.2.3

Post-Publication Verification

Check Method
Version visible Check marketplace/registry
Installable Fresh install test
Changelog visible Check release notes
No errors Check for publish warnings

Agent Responsibilities

DevOps Agent (Two-Stage Release)

  • Stage 1 (Per-Plan): After UAT approval, commit changes locally with detailed message. Do NOT push.
  • Stage 2 (Per-Release): After all plans committed and user approves release, push and publish.
  • Track which plans are committed for current release
  • Coordinate with Roadmap agent to maintain release→plan mappings
  • Never push without explicit release approval
  • Document in agent-output/deployment/

Implementer Agent

  • Update package.json version during milestones
  • Update CHANGELOG.md with changes
  • Commit version updates as part of implementation
  • Follow plan's specified version bump

Planner Agent

  • Specify target release version in plan header
  • Multiple plans may share the same target release
  • Coordinate with Roadmap agent for release assignments
  • Include version update in final milestone

Roadmap Agent

  • Maintain Active Release Tracker section
  • Track current working release version
  • Monitor plan→release mappings
  • Notify when all plans for a release are committed

Rollback Procedure

If release fails:

  1. Unpublish (if platform allows)

    • npm: npm unpublish package@version (within 72h)
    • VS Code: Unpublish via dashboard
  2. Delete tag (if needed)

    git tag -d v1.2.3
    git push origin :refs/tags/v1.2.3
    
  3. Document in deployment log

  4. Notify stakeholders of rollback

See references/release-templates.md for deployment document templates.