A comprehensive release management toolkit for automating changelog generation, version bumping, and release planning based on conventional commits and industry best practices.

Overview

The Release Manager skill provides three powerful Python scripts and comprehensive documentation for managing software releases:

changelog_generator.py - Generate structured changelogs from git history
version_bumper.py - Determine correct semantic version bumps
release_planner.py - Assess release readiness and generate coordination plans

Quick Start

Prerequisites

Python 3.7+
Git repository with conventional commit messages
No external dependencies required (uses only Python standard library)

Basic Usage

# Generate changelog from recent commits
git log --oneline --since="1 month ago" | python changelog_generator.py

# Determine version bump from commits since last tag  
git log --oneline $(git describe --tags --abbrev=0)..HEAD | python version_bumper.py -c "1.2.3"

# Assess release readiness
python release_planner.py --input assets/sample_release_plan.json

Scripts Reference

changelog_generator.py

Parses conventional commits and generates structured changelogs in multiple formats.

Input Options:

Git log text (oneline or full format)
JSON array of commits
Stdin or file input

Output Formats:

Markdown (Keep a Changelog format)
JSON structured data
Both with release statistics

# From git log (recommended)
git log --oneline --since="last release" | python changelog_generator.py \
  --version "2.1.0" \
  --date "2024-01-15" \
  --base-url "https://github.com/yourorg/yourrepo"

# From JSON file
python changelog_generator.py \
  --input assets/sample_commits.json \
  --input-format json \
  --format both \
  --summary

# With custom output
git log --format="%h %s" v1.0.0..HEAD | python changelog_generator.py \
  --version "1.1.0" \
  --output CHANGELOG_DRAFT.md

Features:

Parses conventional commit types (feat, fix, docs, etc.)
Groups commits by changelog categories (Added, Fixed, Changed, etc.)
Extracts issue references (#123, fixes #456)
Identifies breaking changes
Links to commits and PRs
Generates release summary statistics

version_bumper.py

Analyzes commits to determine semantic version bumps according to conventional commits.

Bump Rules:

MAJOR: Breaking changes (feat!: or BREAKING CHANGE:)
MINOR: New features (feat:)
PATCH: Bug fixes (fix:, perf:, security:)
NONE: Documentation, tests, chores only

# Basic version bump determination
git log --oneline v1.2.3..HEAD | python version_bumper.py --current-version "1.2.3"

# With pre-release version
python version_bumper.py \
  --current-version "1.2.3" \
  --prerelease alpha \
  --input assets/sample_commits.json \
  --input-format json

# Include bump commands and file updates
git log --oneline $(git describe --tags --abbrev=0)..HEAD | \
  python version_bumper.py \
  --current-version "$(git describe --tags --abbrev=0)" \
  --include-commands \
  --include-files \
  --analysis

Features:

Supports pre-release versions (alpha, beta, rc)
Generates bump commands for npm, Python, Rust, Git
Provides file update snippets
Detailed commit analysis and categorization
Custom rules for specific commit types
JSON and text output formats

release_planner.py

Assesses release readiness and generates comprehensive release coordination plans.

Input: JSON release plan with features, quality gates, and stakeholders

# Assess release readiness
python release_planner.py --input assets/sample_release_plan.json

# Generate full release package
python release_planner.py \
  --input release_plan.json \
  --output-format markdown \
  --include-checklist \
  --include-communication \
  --include-rollback \
  --output release_report.md

Features:

Feature readiness assessment with approval tracking
Quality gate validation and reporting
Stakeholder communication planning
Rollback procedure generation
Risk analysis and timeline assessment
Customizable test coverage thresholds
Multiple output formats (text, JSON, Markdown)

File Structure

release-manager/
├── SKILL.md                              # Comprehensive methodology guide
├── README.md                             # This file
├── changelog_generator.py                # Changelog generation script
├── version_bumper.py                     # Version bump determination
├── release_planner.py                    # Release readiness assessment
├── references/                           # Reference documentation
│   ├── conventional-commits-guide.md     # Conventional commits specification
│   ├── release-workflow-comparison.md    # Git Flow vs GitHub Flow vs Trunk-based
│   └── hotfix-procedures.md              # Emergency release procedures
├── assets/                               # Sample data for testing
│   ├── sample_git_log.txt               # Sample git log output
│   ├── sample_git_log_full.txt          # Detailed git log format
│   ├── sample_commits.json              # JSON commit data
│   └── sample_release_plan.json         # Release plan template
└── expected_outputs/                     # Example script outputs
    ├── changelog_example.md             # Expected changelog format
    ├── version_bump_example.txt         # Version bump output
    └── release_readiness_example.txt    # Release assessment report

Integration Examples

CI/CD Pipeline Integration

# .github/workflows/release.yml
name: Automated Release
on:
  push:
    branches: [main]

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
      with:
        fetch-depth: 0  # Need full history
        
    - name: Determine version bump
      id: version
      run: |
        CURRENT=$(git describe --tags --abbrev=0)
        git log --oneline $CURRENT..HEAD | \
          python scripts/version_bumper.py -c $CURRENT --output-format json > bump.json
        echo "new_version=$(jq -r '.recommended_version' bump.json)" >> $GITHUB_OUTPUT
        
    - name: Generate changelog
      run: |
        git log --oneline ${{ steps.version.outputs.current_version }}..HEAD | \
          python scripts/changelog_generator.py \
          --version "${{ steps.version.outputs.new_version }}" \
          --base-url "https://github.com/${{ github.repository }}" \
          --output CHANGELOG_ENTRY.md
          
    - name: Create release
      uses: actions/create-release@v1
      with:
        tag_name: v${{ steps.version.outputs.new_version }}
        release_name: Release ${{ steps.version.outputs.new_version }}
        body_path: CHANGELOG_ENTRY.md

Git Hooks Integration

#!/bin/bash
# .git/hooks/pre-commit
# Validate conventional commit format

commit_msg_file=$1
commit_msg=$(cat $commit_msg_file)

# Simple validation (more sophisticated validation available in commitlint)
if ! echo "$commit_msg" | grep -qE "^(feat|fix|docs|style|refactor|test|chore|perf|ci|build)(\(.+\))?(!)?:"; then
    echo "❌ Commit message doesn't follow conventional commits format"
    echo "Expected: type(scope): description"
    echo "Examples:"
    echo "  feat(auth): add OAuth2 integration"
    echo "  fix(api): resolve race condition"
    echo "  docs: update installation guide"
    exit 1
fi

echo "✅ Commit message format is valid"

Release Planning Automation

#!/usr/bin/env python3
# generate_release_plan.py - Automatically generate release plans from project management tools

import json
import requests
from datetime import datetime, timedelta

def generate_release_plan_from_github(repo, milestone):
    """Generate release plan from GitHub milestone and PRs."""
    
    # Fetch milestone details
    milestone_url = f"https://api.github.com/repos/{repo}/milestones/{milestone}"
    milestone_data = requests.get(milestone_url).json()
    
    # Fetch associated issues/PRs
    issues_url = f"https://api.github.com/repos/{repo}/issues?milestone={milestone}&state=all"
    issues = requests.get(issues_url).json()
    
    release_plan = {
        "release_name": milestone_data["title"],
        "version": "TBD",  # Fill in manually or extract from milestone
        "target_date": milestone_data["due_on"],
        "features": []
    }
    
    for issue in issues:
        if issue.get("pull_request"):  # It's a PR
            feature = {
                "id": f"GH-{issue['number']}",
                "title": issue["title"],
                "description": issue["body"][:200] + "..." if len(issue["body"]) > 200 else issue["body"],
                "type": "feature",  # Could be parsed from labels
                "assignee": issue["assignee"]["login"] if issue["assignee"] else "",
                "status": "ready" if issue["state"] == "closed" else "in_progress",
                "pull_request_url": issue["pull_request"]["html_url"],
                "issue_url": issue["html_url"],
                "risk_level": "medium",  # Could be parsed from labels
                "qa_approved": "qa-approved" in [label["name"] for label in issue["labels"]],
                "pm_approved": "pm-approved" in [label["name"] for label in issue["labels"]]
            }
            release_plan["features"].append(feature)
    
    return release_plan

# Usage
if __name__ == "__main__":
    plan = generate_release_plan_from_github("yourorg/yourrepo", "5")
    with open("release_plan.json", "w") as f:
        json.dump(plan, f, indent=2)
    
    print("Generated release_plan.json")
    print("Run: python release_planner.py --input release_plan.json")

Advanced Usage

Custom Commit Type Rules

# Define custom rules for version bumping
python version_bumper.py \
  --current-version "1.2.3" \
  --custom-rules '{"security": "patch", "breaking": "major"}' \
  --ignore-types "docs,style,test"

Multi-repository Release Coordination

#!/bin/bash
# multi_repo_release.sh - Coordinate releases across multiple repositories

repos=("frontend" "backend" "mobile" "docs")
base_version="2.1.0"

for repo in "${repos[@]}"; do
    echo "Processing $repo..."
    cd "$repo"
    
    # Generate changelog for this repo
    git log --oneline --since="1 month ago" | \
        python ../scripts/changelog_generator.py \
        --version "$base_version" \
        --output "CHANGELOG_$repo.md"
    
    # Determine version bump
    git log --oneline $(git describe --tags --abbrev=0)..HEAD | \
        python ../scripts/version_bumper.py \
        --current-version "$(git describe --tags --abbrev=0)" > "VERSION_$repo.txt"
    
    cd ..
done

echo "Generated changelogs and version recommendations for all repositories"

Integration with Slack/Teams

#!/usr/bin/env python3
# notify_release_status.py

import json
import requests
import subprocess

def send_slack_notification(webhook_url, message):
    payload = {"text": message}
    requests.post(webhook_url, json=payload)

def get_release_status():
    """Get current release status from release planner."""
    result = subprocess.run(
        ["python", "release_planner.py", "--input", "release_plan.json", "--output-format", "json"],
        capture_output=True, text=True
    )
    return json.loads(result.stdout)

# Usage in CI/CD
status = get_release_status()
if status["assessment"]["overall_status"] == "blocked":
    message = f"🚫 Release {status['version']} is BLOCKED\n"
    message += f"Issues: {', '.join(status['assessment']['blocking_issues'])}"
    send_slack_notification(SLACK_WEBHOOK_URL, message)
elif status["assessment"]["overall_status"] == "ready":
    message = f"✅ Release {status['version']} is READY for deployment!"
    send_slack_notification(SLACK_WEBHOOK_URL, message)

Best Practices

Commit Message Guidelines

Use conventional commits consistently across your team
Be specific in commit descriptions: "fix: resolve race condition in user creation" vs "fix: bug"
Reference issues when applicable: "Closes #123" or "Fixes #456"
Mark breaking changes clearly with ! or BREAKING CHANGE: footer
Keep first line under 50 characters when possible

Release Planning

Plan releases early with clear feature lists and target dates
Set quality gates and stick to them (test coverage, security scans, etc.)
Track approvals from all relevant stakeholders
Document rollback procedures before deployment
Communicate clearly with both internal teams and external users

Version Management

Follow semantic versioning strictly for predictable releases
Use pre-release versions for beta testing and gradual rollouts
Tag releases consistently with proper version numbers
Maintain backwards compatibility when possible to avoid major version bumps
Document breaking changes thoroughly with migration guides

Troubleshooting

Common Issues

"No valid commits found"

Ensure git log contains commit messages
Check that commits follow conventional format
Verify input format (git-log vs json)

"Invalid version format"

Use semantic versioning: 1.2.3, not 1.2 or v1.2.3.beta
Pre-release format: 1.2.3-alpha.1

"Missing required approvals"

Check feature risk levels in release plan
High/critical risk features require additional approvals
Update approval status in JSON file

Debug Mode

All scripts support verbose output for debugging:

# Add debug logging
python changelog_generator.py --input sample.txt --debug

# Validate input data
python -c "import json; print(json.load(open('release_plan.json')))" 

# Test with sample data first
python release_planner.py --input assets/sample_release_plan.json

Contributing

When extending these scripts:

Maintain backwards compatibility for existing command-line interfaces
Add comprehensive tests for new features
Update documentation including this README and SKILL.md
Follow Python standards (PEP 8, type hints where helpful)
Use only standard library to avoid dependencies

License

This skill is part of the claude-skills repository and follows the same license terms.

For detailed methodology and background information, see SKILL.md. For specific workflow guidance, see the references directory. For testing the scripts, use the sample data in the assets directory.