Version management, release verification, and deployment procedures for software releases. Includes semver guidance, version consistency checks, and platform-specific constraints.
Systematic approach to packaging and releasing software. Use this skill when:
┌─────────────────────────────────────────────────────────────────┐
│ 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 │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
| 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 |
1.2.3-alpha.1 # Early development
1.2.3-beta.1 # Feature complete, testing
1.2.3-rc.1 # Release candidate
| 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 |
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 |
# 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
| 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" }
}
| Constraint | Requirement |
|------------|-------------|
| Version | Standard semver |
| Pre-release | -alpha.1, -beta.1 allowed |
| Deprecation | Use npm deprecate |
| Constraint | Requirement |
|------------|-------------|
| Version | PEP 440 compliant |
| Pre-release | a1, b1, rc1 suffixes |
| Location | setup.py, pyproject.toml, or __version__ |
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
| 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 |
# 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
# Create annotated tag
git tag -a v1.2.3 -m "Release v1.2.3"
# Push tag
git push origin v1.2.3
| Platform | Command |
|----------|---------|
| VS Code | vsce publish |
| npm | npm publish |
| PyPI | twine upload dist/* |
| GitHub | gh release create v1.2.3 |
| Check | Method | |-------|--------| | Version visible | Check marketplace/registry | | Installable | Fresh install test | | Changelog visible | Check release notes | | No errors | Check for publish warnings |
agent-output/deployment/package.json version during milestonesCHANGELOG.md with changesIf release fails:
Unpublish (if platform allows)
npm unpublish package@version (within 72h)Delete tag (if needed)
git tag -d v1.2.3
git push origin :refs/tags/v1.2.3
Document in deployment log
Notify stakeholders of rollback
See references/release-templates.md for deployment document templates.
Search for places (restaurants, cafes, etc.) via Google Places API proxy on localhost.
Interact with GitHub using the `gh` CLI. Use `gh issue`, `gh pr`, `gh run`, and `gh api` for issues, PRs, CI runs, and advanced queries.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Start voice calls via the OpenClaw voice-call plugin.
Notion API for creating and managing pages, databases, and blocks.
Gemini CLI for one-shot Q&A, summaries, and generation.
Category:developer