release-engineering

name	release-engineering
description	Execute releases using semantic versioning and conventional commits — version bump, changelog generation, git tags, and package publishing. Use when the user says "cut a release", "version bump", "changelog", "tag and publish", "semantic versioning", or when shipping work needs a repeatable release procedure. Do not use for deployment-pipeline (CI/CD orchestration), dependency-upgrades (consuming upstream updates), or docs-and-handoff (documentation-only updates).
license	Apache-2.0
compatibility	{"clients":["openai-codex","gemini-cli","opencode","github-copilot"]}
metadata	{"owner":"codex","domain":"release-engineering","maturity":"draft","risk":"low","tags":["release","engineering"]}

Purpose

Execute releases using semantic versioning and conventional commits: determine version bump from commit history, generate changelogs automatically, create git tags and GitHub releases. This makes releases predictable and automated rather than manual and error-prone.

When to use this skill

Use when:

• Cutting a new release of a library/package
• Setting up automated release pipeline
• Writing release notes for a deployment
• Determining what version number to use

Do NOT use when:

• Continuous deployment without versioning (use deployment-pipeline)
• Internal tools that don't need formal releases

Operating procedure

1. Follow Semantic Versioning (SemVer):

   Given version MAJOR.MINOR.PATCH:
   
   MAJOR (1.0.0 → 2.0.0): Breaking API changes
     - Removed public function
     - Changed function signature
     - Renamed public class
   
   MINOR (1.0.0 → 1.1.0): New features, backwards compatible
     - Added new endpoint
     - Added optional parameter
     - Added new class
   
   PATCH (1.0.0 → 1.0.1): Bug fixes, backwards compatible
     - Fixed null pointer
     - Corrected calculation
     - Updated documentation
   
   Pre-release: 1.0.0-alpha.1, 1.0.0-beta.2, 1.0.0-rc.1
   

2. Use Conventional Commits (enables automation):

   Format: <type>[optional scope]: <description>
   
   Types and their version impact:
   ─────────────────────────────────────────────────
   feat:     → MINOR bump (new feature)
   fix:      → PATCH bump (bug fix)
   docs:     → No release (documentation only)
   style:    → No release (formatting)
   refactor: → No release (code change, no behavior change)
   perf:     → PATCH bump (performance improvement)
   test:     → No release (adding tests)
   chore:    → No release (maintenance)
   
   BREAKING CHANGE in footer or ! after type → MAJOR bump
   
   Examples:
   feat(api): add user search endpoint
   fix(auth): handle expired tokens correctly
   feat(api)!: change response format for /users
   
   feat: redesign settings page
   
   BREAKING CHANGE: settings are now stored per-workspace
   

3. Generate changelog from commits:

   # Using conventional-changelog
   npx conventional-changelog -p angular -i CHANGELOG.md -s
   
   # Or manually structured:
   ## [1.2.0] - 2024-01-15
   
   ### Added
   - User search endpoint (#123)
   - Export to CSV feature (#145)
   
   ### Fixed
   - Token expiration handling (#134)
   - Memory leak in background worker (#156)
   
   ### Changed
   - Improved error messages for validation failures
   
   ### Breaking Changes
   - Response format for /users changed (see migration guide)
   

4. Create release workflow:

   # .github/workflows/release.yml
   name: Release
   
   on:
     push:
       tags:
         - 'v*'
   
   
     
        
       
           
           
                
         
           
                 
         
            
            
                  
             
            
           
              
              

Output defaults

## Release Checklist: v[X.Y.Z]

### Pre-release
- [ ] All tests passing on main
- [ ] CHANGELOG.md updated
- [ ] Version bumped in package files
- [ ] Breaking changes documented with migration guide
- [ ] Release notes drafted

### Release
- [ ] Tag created: `git tag -a vX.Y.Z -m "Release vX.Y.Z"`
- [ ] Tag pushed: `git push --tags`
- [ ] GitHub Release created with notes
- [ ] Package published to registry
- [ ] Documentation updated

### Post-release
- [ ] Announce in relevant channels
- [ ] Monitor for issues
- [ ] Update dependent projects

### Release Notes Template
## What's New in vX.Y.Z

### Highlights
- [Major feature or fix]

### Full Changelog
[Link to generated changelog]

### Breaking Changes
[Migration instructions if any]

### Contributors
@contributor1, @contributor2

References

• https://semver.org/
• https://www.conventionalcommits.org/en/v1.0.0/

Failure handling

• Accidental breaking change released as minor: Release new major version immediately with same changes; document in changelog
• Tag pushed but release failed: Delete tag (git tag -d vX.Y.Z && git push --delete origin vX.Y.Z), fix issue, re-tag
• Package registry publish failed: Check credentials, retry; most registries allow republish within short window
• Changelog generator missed commits: Ensure commits follow conventional format; manually add missing entries
• Version conflict in registry: Cannot overwrite published versions; bump version and republish