release-management-standards

Release Management Standards

Guidance for implementing release requirements including versioning, automation, and publishing workflows.

Tooling

Available Tools: If using Claude Code, the agents:release skill can prepare and execute releases with version bumps and validation. The documentation-review:changelog skill manages changelog entries.

Versioning Requirements

Semantic Versioning (MUST)

Projects MUST follow Semantic Versioning (SemVer):

MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD]

Version Examples

1.0.0         # Initial release
1.0.1         # Patch release (bug fix)
1.1.0         # Minor release (new feature)
2.0.0         # Major release (breaking change)
2.0.0-alpha.1 # Pre-release
2.0.0-rc.1    # Release candidate
2.0.0+build.123 # With build metadata

Pre-release Versions (MUST)

Pre-release versions MUST follow this progression:

1. x.y.z-alpha.N - Early testing, unstable
2. x.y.z-beta.N - Feature complete, testing
3. x.y.z-rc.N - Release candidate, final testing

Release Process

Pre-Release Checklist (MUST)

Before releasing, verify:

Release Workflow (MUST)

1. Prepare: Update version, changelog, documentation
2. Validate: Run full test suite and security audit
3. Tag: Create signed Git tag
4. Build: Generate release artifacts
5. Publish: Deploy to package registry
6. Announce: Create GitHub release with notes

Git Tags (MUST)

Release tags MUST:

• Use v prefix: v1.2.3
• Be annotated or signed
• Reference the release commit

# Annotated tag
git tag -a v1.2.3 -m "Release v1.2.3"

# Signed tag (preferred)
git tag -s v1.2.3 -m "Release v1.2.3"

Changelog Management

Changelog Requirements (MUST)

CHANGELOG.md MUST:

• Follow Keep a Changelog format
• Be updated before every release
• Include all notable changes
• Link to comparison between versions

Changelog Entry Structure

## [1.2.0] - 2024-01-15

### Added

- New authentication methods (#123)

### Changed

- Improved error messages (#124)

### Fixed

- Memory leak in parser (#125)

### Security

- Updated dependencies for CVE-2024-001

[1.2.0]: https://github.com/org/repo/compare/v1.1.0...v1.2.0

Release Automation

Automated Releases (SHOULD)

Projects SHOULD implement automated releases:

# GitHub Actions release workflow
name: Release

on:
  push:
    tags:
      - "v*"

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Build
        run: make build

      - name: Create Release
        uses: softprops/action-gh-release@v1
        with:
          generate_release_notes: true
          files: |
            dist/*

Version Bump Automation (SHOULD)

Automate version bumps based on commit types:

Package Publishing

Registry Configuration (MUST)

Configure publishing to appropriate registries:

Publishing Checklist (MUST)

Before publishing:

• Version matches Git tag
• Package metadata complete
• License file included
• README included
• No sensitive data in package
• Dependencies properly declared

Publish Verification (MUST)

After publishing, verify:

• Package installable from registry
• Version appears correctly
• Documentation renders properly
• No missing files

Release Notes

Release Notes Content (MUST)

Release notes MUST include:

• Version number and release date
• Summary of changes
• Breaking changes (highlighted)
• Migration instructions (if needed)
• Contributors acknowledgment

Release Notes Template

# Release v1.2.0

## Highlights

Brief summary of key changes

## Breaking Changes

- Change 1: Migration steps...

## New Features

- Feature 1 (#123)
- Feature 2 (#124)

## Bug Fixes

- Fix 1 (#125)

## Contributors

Thanks to @contributor1, @contributor2

Implementation Checklist

• Define versioning scheme (SemVer)
• Create release checklist
• Set up changelog automation
• Configure Git tag signing
• Implement release workflow
• Configure package registry publishing
• Create release notes template
• Set up release announcement process

Compliance Verification

# Verify version format
echo "v1.2.3" | grep -E "^v[0-9]+\.[0-9]+\.[0-9]+(-[a-z]+\.[0-9]+)?$"

# Check changelog has entry for version
grep -E "^\## \[1\.2\.3\]" CHANGELOG.md

# Verify tag exists and is signed
git tag -v v1.2.3

# Check package version matches
cargo metadata --format-version 1 | jq '.packages[0].version'
npm pkg get version

Additional Resources

Reference Files

• references/release-workflow.md - Detailed release process
• references/versioning-guide.md - Versioning decision guide

Examples

• examples/release.yml - GitHub Actions release workflow
• examples/RELEASE_CHECKLIST.md - Pre-release checklist template