Release Procedures

Atomic Commits: When releasing multiple related plans (e.g., an Epic with FE and BE components), prefer a single atomic "Release vX.Y.Z" commit containing all changes, rather than artificial separation. This simplifies rollback and history.

Semantic Versioning (SemVer)

Version Format: MAJOR.MINOR.PATCH

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

Version Consistency Checklist

All version references must match before release:

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

{
  "version": "1.2.3",
  "engines": { "vscode": "^1.80.0" }
}

npm Packages

Python Packages (PyPI)

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

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

Post-Publication Verification

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/general/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.