445 lines
14 KiB
Markdown
445 lines
14 KiB
Markdown
# Release Manager
|
|
|
|
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:
|
|
|
|
1. **changelog_generator.py** - Generate structured changelogs from git history
|
|
2. **version_bumper.py** - Determine correct semantic version bumps
|
|
3. **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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```yaml
|
|
# .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
|
|
|
|
```bash
|
|
#!/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
|
|
|
|
```python
|
|
#!/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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
#!/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
|
|
|
|
```python
|
|
#!/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
|
|
|
|
1. **Use conventional commits consistently** across your team
|
|
2. **Be specific** in commit descriptions: "fix: resolve race condition in user creation" vs "fix: bug"
|
|
3. **Reference issues** when applicable: "Closes #123" or "Fixes #456"
|
|
4. **Mark breaking changes** clearly with `!` or `BREAKING CHANGE:` footer
|
|
5. **Keep first line under 50 characters** when possible
|
|
|
|
### Release Planning
|
|
|
|
1. **Plan releases early** with clear feature lists and target dates
|
|
2. **Set quality gates** and stick to them (test coverage, security scans, etc.)
|
|
3. **Track approvals** from all relevant stakeholders
|
|
4. **Document rollback procedures** before deployment
|
|
5. **Communicate clearly** with both internal teams and external users
|
|
|
|
### Version Management
|
|
|
|
1. **Follow semantic versioning** strictly for predictable releases
|
|
2. **Use pre-release versions** for beta testing and gradual rollouts
|
|
3. **Tag releases consistently** with proper version numbers
|
|
4. **Maintain backwards compatibility** when possible to avoid major version bumps
|
|
5. **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:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
1. **Maintain backwards compatibility** for existing command-line interfaces
|
|
2. **Add comprehensive tests** for new features
|
|
3. **Update documentation** including this README and SKILL.md
|
|
4. **Follow Python standards** (PEP 8, type hints where helpful)
|
|
5. **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](SKILL.md).
|
|
For specific workflow guidance, see the [references](references/) directory.
|
|
For testing the scripts, use the sample data in the [assets](assets/) directory. |