GitHub Release Creation Skill

This skill helps you create professional, comprehensive GitHub releases using the gh CLI tool. It covers release notes drafting, version management, and best practices for open-source release communication.

When to Use This Skill

Trigger this skill when you encounter requests like:

• "Create a GitHub release for version X.Y.Z"
• "Help me draft release notes"
• "Publish a release with these changes"
• "Compare version A.B.C and version X.Y.Z"
• "Make a release for this project"

Prerequisites

1. GitHub CLI (gh) must be installed and authenticated

   gh auth status
   

   Should show: ✓ Logged in to github.com account <username>

2. Git repository should be properly tagged

   git tag -l "v*"
   

Core Concepts

Version Numbering (Semantic Versioning)

• Major (X.0.0): Breaking changes, major features
• Minor (x.Y.0): New features, backward compatible
• Patch (x.y.Z): Bug fixes, small improvements

Release Types

• Stable Release: Final production-ready version (e.g., v4.0.0)
• Pre-release: Alpha, beta, or RC versions (e.g., v4.0.0-rc.1)
• Draft Release: Work-in-progress release notes

Step-by-Step Release Creation Process

Step 1: Analyze Changes Since Last Release

Identify the base version to compare against:

# Get latest tags
git tag -l "v*" --sort=-version:refname | head -5

# Get commits since last release
git log v3.3.0..HEAD --oneline

# Get detailed commit messages
git log v3.3.0..HEAD --pretty=format:"%h|%ad|%s" --date=short

Key information to extract:

• Commit count since last release
• Major features added
• Bug fixes and improvements
• Breaking changes (if any)
• Performance improvements
• Documentation updates

Step 2: Determine Version Number

Guidelines for choosing version numbers:

Scenario	Version Bump	Example
New major features or breaking changes	Major	v3.3.0 → v4.0.0
New backward-compatible features	Minor	v3.3.0 → v3.4.0
Bug fixes and minor improvements	Patch	v3.3.0 → v3.3.1
Pre-release versions	Suffix	v4.0.0-beta.1, v4.0.0-rc.1

Questions to ask:

• Does this introduce breaking changes? → Major bump
• Are there significant new features? → Minor bump
• Is it primarily bug fixes? → Patch bump

Step 3: Draft Release Notes

Structure professional release notes with these sections:

1. Overview (2-3 sentences)

• High-level summary of the release
• Key theme or focus area
• Version significance (major/minor/patch)

2. What's New (categorized changes)

Organize changes by type:

• ✨ Features: New functionality
• 🔧 Performance: Speed/resource improvements
• 🐛 Bug Fixes: Resolved issues
• 📚 Documentation: Doc updates
• 💥 Breaking Changes: Incompatible changes (if any)
• ♻️ Refactoring: Code quality improvements

3. Comparison with Previous Version

Create comparison tables showing behavior changes:

• Before (vX.Y.Z) → After (vX.Y.Z)
• Performance metrics
• Feature additions
• Configuration changes

4. Migration Guide (if applicable)

• Configuration changes needed
• Breaking changes and how to adapt
• Deprecated features
• Upgrade steps

5. Installation Instructions

# Docker
docker pull user/repo:version

# Build from source
git clone https://github.com/user/repo.git
cd repo
git checkout vX.Y.Z
go build -o binary ./cmd/

# Download binaries
# Link to release assets

6. Full Changelog

List all commits with hashes and dates:

### Commits since v3.3.0
- `9a8ebda` - Fix: Bypass internal HTTP proxy server (2026-01-09)
- `680f785` - Feat: Add SOCKS5 Direct Mode (2025-12-15)

7. Additional Sections (as needed)

• Known Issues
• Credits/Contributors
• License information
• Related links

Step 4: Create Git Tag

# Create annotated tag
git tag -a v4.0.0 -m "Release v4.0.0: Major performance improvements"

# Or create lightweight tag
git tag v4.0.0

# Push tag to GitHub
git push origin v4.0.0

# Or push all tags
git push origin --tags

Step 5: Create GitHub Release Using gh CLI

Basic Release Creation

gh release create v4.0.0 \
  --title "v4.0.0 - Major Performance Release" \
  --notes "Release notes here..."

Advanced Options

# Create release from notes file
gh release create v4.0.0 \
  --title "v4.0.0" \
  --notes-file RELEASE_NOTES.md

# Create draft release (not published yet)
gh release create v4.0.0 \
  --title "v4.0.0" \
  --notes "Draft notes" \
  --draft

# Create pre-release
gh release create v4.0.0-beta.1 \
  --title "v4.0.0-beta.1" \
  --notes "Beta release notes" \
  --prerelease

# Release with target commit
gh release create v4.0.0 \
  --target main \
  --title "v4.0.0" \
  --notes "Release notes"

# Release from existing tag notes
gh release create v4.0.0 \
  --notes-tag \
  --title "v4.0.0"

Release with Assets

# Attach binaries
gh release create v4.0.0 \
  --title "v4.0.0" \
  --notes "Release notes" \
  ./dist/binary-linux-amd64 \
  ./dist/binary-darwin-amd64 \
  ./dist/binary-windows-amd64.exe

# Attach all files from directory
gh release create v4.0.0 \
  --title "v4.0.0" \
  --notes "Release notes" \
  ./dist/*

Step 6: Publish and Verify

# View release
gh release view v4.0.0

# List all releases
gh release list

# Open in browser
gh browse --release v4.0.0

# Edit if needed
gh release edit v4.0.0 --notes "Updated notes"

Release Notes Template

# [Project Name] v[VERSION]

## 🎉 Overview

[2-3 sentence summary of the release]

## 🚀 What's New

### ✨ Features

- **Feature name**: Description of the feature
  - Technical details
  - Benefits for users

### 🔧 Performance Improvements

| Metric | Previous Version | This Version | Improvement |
|--------|-----------------|--------------|-------------|
| Latency | ~100ms | ~50ms | 50% ↓ |
| Memory | 100MB | 85MB | 15% ↓ |

### 🐛 Bug Fixes

- Fixed issue where [description]
- Resolved [problem] by [solution]

### 📚 Documentation

- Updated [file] with [information]
- Added guide for [topic]

## 📊 Comparison with v[PREVIOUS_VERSION]

### Behavior Changes

| Scenario | v[PREVIOUS] | v[CURRENT] |
|----------|-------------|------------|
| Feature A | Old behavior | **New behavior** |

### Technical Details

- **Architecture**: [description of changes]
- **Modified Files**:
  - [file1](link) - Change description
  - [file2](link) - Change description

## 🔄 Migration from v[PREVIOUS]

### ✅ No Configuration Changes Required

[If applicable: "This release is 100% backward compatible"]

### Breaking Changes

[If any: List breaking changes and migration steps]

## 🛠️ Installation

### Docker
```bash
docker pull user/repo:v[VERSION]

Build from Source

git clone https://github.com/user/repo.git
cd repo
git checkout v[VERSION]
[build commands]

Download Binaries

Download from Releases page.

📋 Full Changelog

Commits since v[PREVIOUS]

• hash - Type: Description (date)
• hash - Type: Description (date)

🐛 Known Issues

[List any known issues or "None reported"]

🙏 Credits

Contributors:

• @username1
• @username2

📄 License

[License information]

🔗 Links

• Documentation
• Migration Guide
• GitHub Repository

---

Full Changelog: https://github.com/user/repo/compare/v[PREVIOUS]...v[CURRENT]

## Best Practices

### DO ✅

1. **Use semantic versioning** consistently
2. **Write comprehensive release notes** that stand alone
3. **Include installation instructions** for common use cases
4. **Highlight breaking changes** prominently
5. **Credit contributors** who helped with the release
6. **Link to related issues/PRs** when relevant
7. **Use consistent formatting** (Markdown tables, code blocks)
8. **Test the release process** on a test repository first
9. **Keep release notes concise but complete**
10. **Include comparison data** for performance changes

### DON'T ❌

1. **NEVER create releases without proper tagging**
2. **NEVER skip authentication check** before creating releases
3. **NEVER publish release notes without review**
4. **DON'T use internal jargon** without explanation
5. **DON'T forget to verify** the release after creation
6. **DON'T create major releases** for trivial changes
7. **DON'T skip backward compatibility notes** for breaking changes
8. **DON'T forget to push tags** to remote repository
9. **DON'T use vague commit messages** (improves changelog quality)
10. **NEVER release untested code** to production

## Common Workflows

### Workflow 1: Regular Feature Release

```bash
# 1. Checkout main branch
git checkout main
git pull

# 2. Review changes since last release
git tag -l "v*" --sort=-version:refname | head -1
git log v3.3.0..HEAD --oneline

# 3. Determine version (e.g., v3.4.0 for new features)

# 4. Create tag
git tag -a v3.4.0 -m "Release v3.4.0: New features and improvements"
git push origin v3.4.0

# 5. Create release (from prepared notes file)
gh release create v3.4.0 \
  --title "v3.4.0 - New Features" \
  --notes-file RELEASE_NOTES.md

Workflow 2: Hotfix Patch Release

# 1. Create hotfix branch
git checkout -b hotfix/critical-bug-fix

# 2. Make fix and commit
git commit -m "fix: Critical security vulnerability"

# 3. Create patch tag
git tag -a v3.3.1 -m "Release v3.3.1: Critical security fix"
git push origin hotfix/critical-bug-fix v3.3.1

# 4. Create release with urgent notes
gh release create v3.3.1 \
  --title "v3.3.1 - Security Fix" \
  --notes "## 🚨 Security Fix

This release addresses a critical security vulnerability.

**Upgrade immediately if you are affected.**

[Fix details]"

Workflow 3: Major Version Release

# 1. Comprehensive changelog analysis
git log v3.0.0..HEAD --pretty=format:"%h|%ad|%s" --date=short > changes.txt

# 2. Create migration guide
# Write MIGRATION.md with breaking changes

# 3. Create major tag
git tag -a v4.0.0 -m "Release v4.0.0: Major architecture improvements"
git push origin v4.0.0

# 4. Create comprehensive release
gh release create v4.0.0 \
  --title "v4.0.0 - Major Release" \
  --notes-file COMPREHENSIVE_NOTES.md \
  --draft

# 5. Review and publish
gh release view v4.0.0 --web
# (Review in browser, then publish when ready)

Workflow 4: Pre-release (Beta/RC)

# 1. Create pre-release tag
git tag -a v4.0.0-beta.1 -m "Beta 1 for v4.0.0"
git push origin v4.0.0-beta.1

# 2. Create pre-release
gh release create v4.0.0-beta.1 \
  --title "v4.0.0-beta.1 - Testing Release" \
  --notes "## 🧪 Beta Release

This is a pre-release for testing purposes.

**Not recommended for production use.**

[Features to test]" \
  --prerelease

# 3. After testing, create final release
git tag -a v4.0.0 -m "Release v4.0.0"
git push origin v4.0.0
gh release create v4.0.0 --notes "Final release notes"

Troubleshooting

Issue: "gh not authenticated"

Solution:

gh auth login
gh auth status  # Verify

Issue: "Tag not found"

Solution:

# Push tag first
git push origin <tag-name>

# Or verify tag exists
git tag -l | grep <tag-name>

Issue: "Release already exists"

Solution:

# Delete existing release
gh release delete <tag-name> --yes

# Or edit existing release
gh release edit <tag-name> --notes "New notes"

Issue: "Permission denied"

Solution:

• Verify repository permissions: gh repo view
• Check authentication: gh auth status
• Ensure you have admin/write access

Additional Resources

• GitHub Releases Documentation
• GitHub CLI Manual
• Semantic Versioning
• Keep a Changelog

Tips for High-Quality Releases

1. Start Early: Begin drafting release notes during development
2. Track Features: Maintain a CHANGELOG.md file
3. Communicate: Use issues/PRs to discuss release plans
4. Test Thoroughly: Test installation instructions
5. Be Honest: Clearly document known issues
6. Celebrate: Highlight community contributions
7. Stay Organized: Use consistent structure across releases
8. Provide Context: Explain why changes matter to users
9. Include Metrics: Use data to demonstrate improvements
10. Link Forward: Point to next version or roadmap

Example Commands Reference

# View all gh release commands
gh release --help

# Create release from stdin
echo "Release notes" | gh release create v1.0.0

# Create release with discussion
gh release create v1.0.0 \
  --discussion "Discuss v1.0.0 release"

# Delete release
gh release delete v1.0.0 --yes

# Download release assets
gh release download v1.0.0 \
  --dir ./downloads \
  --pattern "*.zip"

# List releases
gh release list \
  --limit 20 \
  --json name,tagName,publishedAt

---

Remember: Good releases communicate value, build trust, and make users excited about your project!