Release Management

Release Management Workflow

This workflow describes how releases are managed for the ruby-git gem.

Contents

• How to use this skill
• Related skills
• How Releases Work
• Developer Responsibilities
• Checking Release Readiness
• Cutting a maintenance branch
• Major release readiness
• After a major release
• What NOT to Do
• Useful Commands

How to use this skill

Attach this file to your Copilot Chat context when preparing a release, verifying release readiness, or answering questions about versioning and publishing flow.

Related skills

• Dependency Management — dependency updates that affect release content and risk
• PR Readiness Review — ensure changes are release-ready before merge
• Breaking Change Analysis — evaluate and communicate major-version impact

How Releases Work

Releases are fully automated via release-please and the .github/workflows/release.yml workflow:

1. Developers merge PRs with conventional commit messages into a release branch: main for the next major, or a maintenance branch such as 5.x or 4.x for a patch or minor release of an earlier series
2. release-please automatically opens (and keeps updated) a release PR that bumps lib/git/version.rb and regenerates CHANGELOG.md
3. When a maintainer merges the release PR, release-please creates a GitHub release with a tag
4. The workflow then publishes the gem to RubyGems.org via rubygems/release-gem

Key config files:

prerelease is false, so release-please never proposes a beta and every release is a normal release. The config also sets bump-minor-pre-major: true and bump-patch-for-minor-pre-major: true, which affect version bumps only while the major version is 0.

Developer Responsibilities

The only thing developers need to do for releases is use conventional commit messages. release-please determines the version bump from commit types:

• fix: → patch bump
• feat: → minor bump
• feat!: or BREAKING CHANGE: footer → major bump

Everything else (version bump, changelog, tag, gem push) is automated. Do not manually edit lib/git/version.rb or CHANGELOG.md.

Checking Release Readiness

Before a maintainer merges a release PR:

1. Ensure CI passes on the release branch (main, 5.x, or 4.x):

   bundle exec rake default

2. Review unreleased changes since last tag:

   git log $(git describe --tags --abbrev=0)..HEAD --oneline

3. Check for open blockers:

   gh issue list --label "bug" --state open

4. Review the release PR — verify the auto-generated changelog and version bump look correct.

5. Retire the release banner — if README.md opens with a banner announcing this major's .0.0 release and the release PR is the major's first minor, merge a docs PR that removes the banner before merging the release PR. The banner announces the major; once the series has a minor, the dated announcement entry carries the history.

Cutting a maintenance branch

main becomes the release line for the next major as soon as the first removal merges (ADR-0007), which can be long before that major ships. Cut the maintenance branch for the current major at that point, not after the major release, so the series can keep releasing while main is pinned to the next major.

The cut is two pull requests, one into each branch, because each branch runs its own copy of the workflows. Both carry the same docs commit: write it once, cherry-pick it onto the other branch, and cherry-pick it again whenever review changes it on either side, so the two branches say the same thing. Merge the main PR first so the pin is in place before anything else lands on main. Below, <N> is the major being cut, <N+1> the major main will release next, and <M> the major of the maintenance branch that already exists.

On main:

• Add a README announcement entry dated the cut day: every further v<N>.x release comes from the new branch, and the next release from main is v<N+1>.0.0.
• Put a development note at the top of README.md, replacing the release banner if one is still there: main is unreleased v<N+1>.0.0 development, the current release series is v<N>.x, released from the new branch, and the "Upgrading to v<N+1>.x" section of UPGRADING.md says what changes. Name the series, not a tag: later v<N>.x releases do not touch main, so a tag in the note would go stale. This goes on a main-only commit, never on the shared docs commit: the new branch keeps whatever README.md opened with at the branch point.
• Pin the next release from main to the next major with a Release-As: <N+1>.0.0 footer on the announcement commit. Without the pin, the first commit merged to main after the cut has release-please open a release PR for the next v<N> patch or minor from main, colliding with the release stream on the new branch. release-please reads the footer from any commit since the last tag, so the pin holds until the major ships and then expires on its own. The footer goes on a main-only commit and never on the shared docs commit, which is cherry-picked onto the new branch and would pin that branch's next release to the major too. Do not use the release-as key in .release-please-config.json instead: it applies to every release PR until someone remembers to remove it.

On the new branch:

• Create the branch <N>.x from the latest tag of that major and protect it with a ruleset named Release Branch (<N>.x), copied from Release Branch (default). The copy requires the same status checks as main. Until the next item lands, the only PR that can satisfy them is that item's own, whose head carries the triggers.
• Add the branch to the push trigger and the release job guard in release.yml, to the pull_request triggers in continuous_integration.yml and enforce_conventional_commits.yml, and to the push trigger in warm_bundler_caches.yml, all under .github/workflows/. The workflow that runs is the one on the branch pushed to or targeted, and a Bundler cache is readable only from the ref that wrote it, its base ref, and the default branch, so the copies on main need no change.
• Expect release-please to open a release PR from the new branch as soon as this PR merges. No commit type is hidden in .release-please-config.json, so the workflow and docs commits alone propose the next patch. Leave that release PR open until the series has something worth releasing, or merge it.

On both, in the shared docs commit:

• Name the new branch beside the existing maintenance branch everywhere that one is listed: the branch tables in .github/copilot-instructions.md and CONTRIBUTING.md, the release support policy in README.md, the protected branch list in .husky/pre-commit, and the skills that list the protected branches. grep -rn '<M>\.x' .github .husky CONTRIBUTING.md README.md, with the existing maintenance branch's major in place of <M>, finds them all.