| name | release |
| description | Creates a new ButterCut release with version bump, changelog, git tag, gem build, and GitHub release. Use when publishing a new version. |
Skill: Release ButterCut
Guides through the complete release process: version bump, changelog, git operations, gem publishing, and GitHub release creation.
When to Use
- Publishing a new version of ButterCut
- After merging features or fixes that should be released
- Creating the first v0.1.0 release
Workflow
1. Run Tests First
CRITICAL: Always run tests before releasing. Never release if tests fail.
bundle exec rspec
If any tests fail, STOP immediately and ask user to fix before proceeding with release.
2. Check Current State
cat lib/buttercut/version.rb
git status
git tag -l
If git status is not clean, stop and ask user to commit or stash changes before proceeding.
3. Determine New Version
Ask user what type of release following Semantic Versioning:
- MAJOR (1.0.0): Breaking changes
- MINOR (0.2.0): New features, backward compatible
- PATCH (0.1.1): Bug fixes, backward compatible
Calculate new version number based on current version and release type.
4. Update Version File
Edit lib/buttercut/version.rb with the new version:
class ButterCut
VERSION = "0.2.0"
end
5. Gather Changelog Notes
Ask user for release notes. Prompt with:
- What changed in this release?
- Any new features?
- Any bug fixes?
- Any breaking changes?
6. Update or Create CHANGELOG.md
If CHANGELOG.md exists, prepend new entry. Otherwise create it:
# Changelog
All notable changes to ButterCut will be documented in this file.
## [0.2.0] - 2025-01-21
### Added
- Feature X
- Support for Y
### Fixed
- Bug in Z
### Changed
- Improved W
7. Commit Version Bump
git add lib/buttercut/version.rb CHANGELOG.md
git commit -m "Bump version to 0.2.0"
8. Create and Push Git Tag
git tag v0.2.0
git push origin main
git push origin v0.2.0
9. Build Gem
gem build buttercut.gemspec
This creates buttercut-0.2.0.gem file.
10. Publish to RubyGems
First time setup check:
If this is the first release, verify RubyGems authentication:
gem signin
If not authenticated, provide instructions:
- Sign up at https://rubygems.org
- Run
gem signin and follow prompts
- Store credentials for future releases
Publish the gem:
gem push buttercut-0.2.0.gem
This makes the gem available for gem install buttercut worldwide.
11. Create GitHub Release
Using GitHub CLI:
gh release create v0.2.0 \
--title "v0.2.0" \
--notes "[Release notes from changelog]" \
buttercut-0.2.0.gem
If gh CLI not available:
Guide user through manual release creation:
- Go to https://github.com/andrewford/buttercut/releases/new
- Choose tag: v0.2.0
- Set title: v0.2.0
- Paste changelog notes in description
- Attach buttercut-0.2.0.gem file
- Click "Publish release"
Then wait for user confirmation that release is created before proceeding to cleanup.
12. Cleanup
rm buttercut-0.2.0.gem
13. Verify Release
Check that everything worked:
14. Return Success Response
Provide summary:
✓ ButterCut 0.2.0 released successfully
Version: 0.2.0
Git tag: v0.2.0
RubyGems: Published at https://rubygems.org/gems/buttercut
GitHub Release: https://github.com/andrewford/buttercut/releases/tag/v0.2.0
Installation:
gem install buttercut
Upgrade:
gem update buttercut
Critical Principles
Always run tests first - Never release if tests fail
Git must be clean - No uncommitted changes before release
Push before publish - Tags must be pushed before creating GitHub release
Semantic versioning - Follow semver strictly for version numbers
Changelog required - Every release needs documented changes
Common Issues
Tests failing: Ask user to fix tests before proceeding
Git not clean: Ask user to commit or stash changes first
Tag already exists: Verify this isn't a duplicate release
RubyGems authentication: Guide through gem signin process
GitHub CLI not installed: Provide manual release instructions
