release

name	release
description	Cut a new release of the badge gem — verify via make smoke, build, tag, push, publish to rubygems, and write a GitHub release matching the project's 2018-era house style. Use when asked to "release", "cut a release", "publish a new version", "tag a release", "new release", "/release", "ship it", or "prepare a release".

Release the badge gem

The project's release ritual. Every step is required unless explicitly marked optional. Don't freelance — match the conventions below so git tag -l and gh release list stay consistent with the last decade of history.

Before you start

Verify all of these. If any is false, stop and fix it first.

• On master and up-to-date with origin
• Working tree clean
• All release-worthy PRs merged
• make smoke passes on plain master

git status                                        # clean working tree
git pull --ff-only                                # up-to-date with origin
git log --oneline origin/master -5                # sanity check
make smoke                                        # must be 20/20

Step 1: Pick the next version

Semver:

• patch (0.13.2 → 0.13.3) — bugfixes, no new options, no breaking changes
• minor (0.13.2 → 0.14.0) — new CLI options or new features
• major (0.13.2 → 1.0.0) — breaking changes only, discuss first

The gem has been 0.x since 2015 — don't jump to 1.0 without explicit agreement from the maintainer.

grep VERSION lib/badge/base.rb                    # current version
git tag --sort=-v:refname | head -5               # most recent tags

Step 2: Bump VERSION if not already done

The project's convention is to bundle the VERSION bump into the final feature PR, not as a separate bump commit. If the VERSION on master already matches your target, skip to Step 3.

Otherwise bump it now on a short-lived branch and merge via PR (don't push directly to master):

git checkout -b release/X.Y.Z
# edit lib/badge/base.rb: VERSION = "X.Y.Z"
git commit -am "chore: bump version to X.Y.Z"
git push -u origin release/X.Y.Z
gh pr create --title "Release X.Y.Z" --body "Version bump for upcoming release." --base master
# merge after review, then back to master and pull

Step 3: Verify — mandatory

make smoke is the only test suite this project has. 20 end-to-end cases. Must be 20/20 before tagging. Do not skip even if "nothing looks changed."

bundle install                                    # if vendor/bundle is stale
make smoke

If anything fails, do not release. Fix the regression first.

Step 4: Build the gem

make build                                        # → badge-X.Y.Z.gem

Verify the file list inside. Expected contents (13 files): bin/badge, lib/badge.rb, lib/badge/*.rb (5 files), README.md, LICENSE, and the 4 PNGs under assets/.

tar -xOf badge-X.Y.Z.gem data.tar.gz | tar -tzf - | sort

Step 5: Create the tag

Annotated tags. Name = plain version number (no v prefix). Message = Release X.Y.Z. This matches every tag from 0.4.x onward.

git tag -a X.Y.Z -m "Release X.Y.Z" master
git push origin X.Y.Z

Verify the tag landed:

git cat-file -t X.Y.Z                                         # should print "tag"
gh api repos/HazAT/badge/git/refs/tags/X.Y.Z --jq '.object.sha'

Step 6: Publish to rubygems

macOS PATH gotcha — read this

/usr/bin/gem is system Ruby 2.6, which cannot load the Homebrew Ruby 4.x gems in ~/.gem/gems/. Symptoms: incompatible library version errors, hash key "*" is not a Symbol from rdoc, or syntax errors from modern JSON. Fix the PATH before running any gem command:

export PATH="/opt/homebrew/opt/ruby@4/bin:$PATH"
unset GEM_HOME GEM_PATH
which gem                                         # expect /opt/homebrew/opt/ruby@4/bin/gem

On a dev machine this lives permanently in ~/.zshenv — if a contributor hits the error above, that's the fix.

Sign in (interactive — first time on a machine)

gem signin                                        # prompts for email, password, OTP

Push

gem push badge-X.Y.Z.gem

If the agent doesn't have rubygems credentials, hand the push back to the user with the exact command above. Don't prompt for credentials or try to write to ~/.gem/credentials — let the user run gem signin in their own terminal.

Step 7: Create the GitHub release

Match the 2018-era house style exactly — every release from 0.4.x to 0.8.7 follows this format, and 0.13.2 revived it. The rules:

• Empty title (tag name becomes the display title)
• Terse bullet list, one line per change
• type: <summary> #<pr> format for each bullet (feat, fix, docs, chore)
• No markdown headers, no "What's Changed" boilerplate
• @-mention external contributors at the bottom — they get a notification

gh release create X.Y.Z --title "" --notes '- feat: <summary> #<pr>
- fix: <summary> #<pr>

Thanks @contributor for the PR.'

If a prior version was tagged but never released

(E.g. 0.13.1 existed as a tag but was never published as a GH release.) Roll it up with a note at the bottom:

Rolls up X.Y.N + X.Y.(N+1) (X.Y.N was never tagged or published).

Step 8: Verify live and clean up

# Confirm rubygems has the new version
curl -s https://rubygems.org/api/v1/gems/badge.json | \
  ruby -rjson -e 'd = JSON.parse(STDIN.read); puts "#{d["version"]}  (#{d["version_created_at"][0,19]})"'

# Confirm a fresh install works
TMP=$(mktemp -d) && GEM_HOME=$TMP gem install badge --version X.Y.Z --no-document && rm -rf $TMP

# Tidy the local .gem artifact (gitignored, but clean up anyway)
rm -f badge-X.Y.Z.gem

Step 9: Report

Summarize what shipped. Include:

• The rubygems URL (https://rubygems.org/gems/badge/versions/X.Y.Z)
• The GitHub release URL
• Any contributors to thank
• Any follow-up work (e.g. "roll next minor when we land #113")

Gotchas to remember

• fastlane-plugin-badge pins badge ~> 0.13.0 (or similar). Patch and minor releases under 0.13.x ship to fastlane users transparently — no sister-gem bump needed. A 0.14 bump would require updating the plugin's constraint.
• The tag points at master tip (merge commit), not the VERSION-bump commit. All 0.x tags follow this pattern.
• No CHANGELOG file exists in the repo. The GitHub release notes serve as release history.
• GitHub releases were skipped 2018–2025. Don't take that as convention — every release going forward should have one.
• Don't commit badge-X.Y.Z.gem or vendor/ — both are in .gitignore but if you see them in git status, something's off.
• Never publish from a dirty working tree. git status must be clean before gem push.