Release with release-please

Open
  • Is something wrong?
#785 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
15/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Tech stack
github-actions, ruby
Domain
ci-cd, release

Research direction

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.

Written by the indexing model from the issue text.

Description

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.

Dominant language
Ruby
Stars
3.7k
Forks
381
Avg merge
17h 10m
Merged PRs (30d)
11

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from jwt/ruby-jwt

All issues in jwt/ruby-jwt

Similar issues

More Ruby issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.