Release with release-please

Start with the plan's first item: jwk-loader 1.3.0 must publish through release-please before this setup is copied. The work touches lib/jwt/version.rb (MAJOR/MINOR/TINY annotations), push_gem.yml (adding workflow_call and workflow_dispatch), a new release-please.yml, and CONTRIBUTING.md plus the PR template. Done means the first release-please release PR, tag, GitHub release and RubyGems gem all succeed after the manual steps are removed.

Releasing is manual today: bump version.rb right after each release, add a changelog row in every PR, tag the release by hand, and create the GitHub release by hand. release-please automates all of that from commit messages. It keeps a release PR open, and merging that PR tags the release, creates the GitHub release with its changelog section, and publishes the gem. anakinj/jwk-loader already releases this way, so its config and workflows are the starting point.

Start this after 3.3.1 is released the current way. None of the commits since v3.3.0 use conventional titles, so release-please would generate an empty changelog for them, and releasing first gives a clean cut-over.

Plan

• Wait for jwk-loader 1.3.0 to publish through release-please. That gem's publish job hasn't succeeded on a real release yet. If it fails, fix it there before copying the setup.
• Release 3.3.1 the current way.
• Require conventional PR titles. Pull requests are squash merged with the PR title as the commit message, so the title is what release-please reads. A PR adding a title check is ready, together with a ci prefix for Dependabot and documentation in CONTRIBUTING.md and the PR template. Once it's merged, make the check a required status check on main.
• Add the release-please config: release-type: ruby, include-v-in-tag: true so tags stay vX.Y.Z, and a manifest set to 3.3.1. Use changelog-sections for the changelog format described under Decisions.
• Make the version file updatable. lib/jwt/version.rb uses separate MAJOR, MINOR and TINY constants, which the Ruby updater most likely doesn't rewrite. Add the generic x-release-please-major, -minor and -patch annotations to those lines and list the file under extra-files, rather than restructuring it.
• Publish from the release job. Add release-please.yml, and give push_gem.yml a workflow_call trigger so the release job can call it, plus workflow_dispatch with a tag input to re-publish an existing tag if publishing fails. Tags created with GITHUB_TOKEN don't trigger other workflows, so the tag trigger alone won't fire. That keeps the existing tag and version check, build, push and wait steps.
• Check the RubyGems trusted publishing role. The policy behind RUBYGEMS_PUSH_ROLE may only allow tag refs or push_gem.yml, and publishing from a reusable workflow called on main may need it widened.
• Dry run before merging with the release-please CLI's --dry-run, to confirm it bumps the version constants and writes the changelog as intended.
• Remove the manual steps: the NEXT changelog section and its Your contribution here placeholders, the changelog row requirement in CONTRIBUTING.md and the PR template, and the manual release steps. release-please adds new sections under # Changelog.
• Confirm the first release: the release PR, the tag, the GitHub release and the gem on RubyGems.

Decisions

• Changelog format (decided): release-please's default changelog, with custom sections. changelog-sections maps feat to Features, fix and perf to Fixes and enhancements, and revert to Reverts, and hides refactor, docs, test, ci, build and chore. Entries are taken from PR titles, so titles are worth editing before merging, and a user-visible change needs a feat or fix title to appear. Authors are no longer credited in the changelog or the GitHub release. If that's missed, changelog-type: github brings credit back with one config change.
• Release names. GitHub releases are named jwt-3.3.0 today, and release-please will probably name them v3.4.0. Check whether that matters to anyone, and whether the config can keep the current name.
• CI on release PRs. release-please opens them with GITHUB_TOKEN, so CI won't run on them. They only change the version and changelog, so that's probably fine. Otherwise use a GitHub App token.
• 2-10-stable. Keep releasing 2.x manually for now. release-please can manage a second branch later if needed.

Posted by Claude on behalf of @anakinj.