release-management

name	release-management
description	Prepares and publishes new releases of the ruby-git gem including version bumps, changelog updates, tagging, and gem publishing. Use when preparing a release or checking release readiness.

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:

File	Purpose
.release-please-config.json	Release-please settings (release type, changelog sections, versioning strategy)
.release-please-manifest.json	Tracks the current released version
lib/git/version.rb	Version constant (updated automatically by release-please)
CHANGELOG.md	Release history (updated automatically by release-please)

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.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.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.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 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.

Major release readiness

Before merging the release PR for a major version, run Checking Release Readiness, then confirm each item below. The per-PR removal gate lives in Breaking Change Analysis, Step 4 and is checked when each removal PR merges, not here.

• Version floors are updated everywhere they are set: required_ruby_version in git.gemspec, TargetRubyVersion in .rubocop.yml, the CI workflow matrices under .github/workflows/, Git::MINIMUM_GIT_VERSION in lib/git.rb, the README "Ruby version support policy" and "Git version support policy" subsections, and the Compatibility list in Project Context. Include any RuboCop cleanup a TargetRubyVersion bump triggers.
• ADR-0004 audit: the options the new git floor kills are deprecated in this major (ADR-0004).
• Carried deprecations, if any, have their warning text, @deprecated YARD tag, and UPGRADING.md entry updated to name the major the roadmap decided for them, or "a future major release" while that is undecided, and the horizon passed to ActiveSupport::Deprecation.new in lib/git.rb is bumped to the next major.
• The "Upgrading to vN.0.0" section of UPGRADING.md is complete.
• README examples use no removed APIs.
• The changelog preview in the release PR reads correctly and every removal commit carries a BREAKING CHANGE footer.
• The development note at the top of README.md is replaced with a release banner naming the new major and linking to UPGRADING.md and CHANGELOG.md, in a docs PR merged before the release PR. README.md ships in the gem and on RubyDoc, so a banner added after the release never reaches the major's own artifact. The major's first minor release removes the banner; see Checking Release Readiness.

After a major release

• Add a README announcement entry dated the release day.
• Support for the oldest maintenance branch ends with this release (see the release support policy in README.md). Retire it everywhere it is named. In the workflow triggers and release job guard under .github/workflows/, replace it with the newer maintenance branch, which the cutting step left out of the copies on main. Everywhere else the newer branch is already listed, so remove the retired one: 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 retired branch's major in place of <M>, finds them all.
• Close the milestone and update the roadmap issue.

What NOT to Do

• Do not manually bump lib/git/version.rb — release-please does this
• Do not manually edit CHANGELOG.md — it is auto-generated from commits
• Do not manually create tags — release-please creates them on merge
• Do not manually gem push — the workflow handles publishing
• Do not force-push or rebase the release PR — release-please manages it

Useful Commands

# View recent tags
git tag -l --sort=-v:refname | head -10

# List commits since last release
git log $(git describe --tags --abbrev=0)..HEAD --oneline

# Compare with previous release
git diff $(git describe --tags --abbrev=0)..HEAD

# Check current version
ruby -e "require_relative 'lib/git/version'; puts Git::VERSION"

# View release-please config
cat .release-please-config.json | jq .

# Build gem locally (for testing only)
bundle exec rake build
gem install pkg/git-*.gem