github-release

name	github-release
description	Use this skill when the user asks to "create a GitHub release", "publish a release", "make a release", "draft release notes", or needs guidance on using gh CLI to manage GitHub releases. This skill specializes in creating comprehensive, well-formatted GitHub releases using the GitHub CLI (gh).
version	1.0.0
license	MIT

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!