@seanspiesman/release-procedures

---
name: release-procedures
description: Version management, release verification, and deployment procedures for software releases. Includes semver guidance, version consistency checks, and platform-specific constraints.
license: MIT
metadata:
  author: groupzer0
  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

```bash
# 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 |

```json
{
  "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](https://keepachangelog.com/):

```markdown
# 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

```bash
# 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

```bash
# 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)
   ```bash
   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](references/release-templates.md) for deployment document templates.