| name | backstage-release |
| description | Cut a new Backstage gem release. Bumps version, writes CHANGELOG entry, commits, tags, and pushes to trigger the GitHub Actions publish workflow. |
backstage-release
Cut a new release of the Backstage gem. Work through each step in order, confirming with the user before making changes.
Step 1 — Confirm everything is ready
Before touching any files, check:
- Run
bundle exec rake test — all tests must pass. Stop if any fail.
- Run
standardrb — no offences. Stop if any fail.
- Check
git status — working tree must be clean (all changes committed). Stop if dirty.
Report results before proceeding.
Step 2 — Determine the new version number
Read lib/backstage/version.rb to get the current version.
Ask the user: "Current version is X.Y.Z. What should the new version be?"
Follow Semantic Versioning:
- Patch (X.Y.Z+1) — bug fixes, no new API
- Minor (X.Y+1.0) — new features, backwards compatible
- Major (X+1.0.0) — breaking changes
Step 3 — Collect release notes
Ask: "What should go in the CHANGELOG for this release?"
If the user isn't sure, run git log vPREVIOUS..HEAD --oneline (where PREVIOUS is the last tagged version from git tag --sort=-v:refname | head -1) to show commits since the last release. Summarise them into bullet points grouped as Added / Changed / Fixed / Removed, and confirm with the user before writing.
Step 4 — Bump the version
Edit lib/backstage/version.rb:
module Backstage
VERSION = "NEW_VERSION"
end
Step 5 — Update CHANGELOG.md
Read the current CHANGELOG.md. Add a new section above the most recent release entry (but below ## [Unreleased]):
## [NEW_VERSION] — YYYY-MM-DD
### Added
- ...
### Fixed
- ...
Use today's date. Only include sections (Added / Changed / Fixed / Removed) that have entries. Move anything from ## [Unreleased] into this section and leave ## [Unreleased] empty.
Step 6 — Commit
Stage only release files:
git add lib/backstage/version.rb CHANGELOG.md
git commit -m "Release v{NEW_VERSION}"
Step 7 — Tag and push
git tag vNEW_VERSION
git push origin main
git push origin vNEW_VERSION
Pushing the tag triggers the GitHub Actions publish workflow (.github/workflows/publish.yml), which builds and pushes the gem to RubyGems automatically.
Step 8 — Create GitHub release
Use the CHANGELOG entry for this version as the release notes:
gh release create vNEW_VERSION --title "vNEW_VERSION" --notes "CHANGELOG_NOTES"
Confirm with the user before creating.
Step 9 — Verify
Summary
After completion, print:
- New version number
- Tag pushed
- GitHub release URL (returned by
gh release create)
- Link to the GitHub Actions run (if available from
gh run list --workflow=publish.yml --limit=1)
- Any manual steps remaining (e.g. if the publish workflow is not configured)
