gh-release-skill

--- 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** ```bash gh auth status ``` Should show: `✓ Logged in to github.com account ` 2. **Git repository should be properly tagged** ```bash 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: ```bash # 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** ```bash # 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: ```markdown ### 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 ```bash # 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 ```bash gh release create v4.0.0 \ --title "v4.0.0 - Major Performance Release" \ --notes "Release notes here..." ``` #### Advanced Options ```bash # 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 ```bash # 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 ```bash # 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 ````markdown # [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 ```bash git clone https://github.com/user/repo.git cd repo git checkout v[VERSION] [build commands] ``` ### Download Binaries Download from [Releases](https://github.com/user/repo/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](link) - [Migration Guide](link) - [GitHub Repository](link) --- **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 ```bash # 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 ```bash # 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) ```bash # 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:** ```bash gh auth login gh auth status # Verify ``` ### Issue: "Tag not found" **Solution:** ```bash # Push tag first git push origin # Or verify tag exists git tag -l | grep ``` ### Issue: "Release already exists" **Solution:** ```bash # Delete existing release gh release delete --yes # Or edit existing release gh release edit --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](https://docs.github.com/en/repositories/releasing-projects-on-github) - [GitHub CLI Manual](https://cli.github.com/manual/) - [Semantic Versioning](https://semver.org/) - [Keep a Changelog](https://keepachangelog.com/) ## 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 ```bash # 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!