Skip to main content
Last updated: 1 Aug 2024

Publish a Ruby gem

Conventions

For conventions around naming, refer to the RubyGems naming guide and the GOV.UK naming policy.

Follow Semantic Versioning and put version updates in their own commit.

Follow the file and directory conventions used by Bundler.

Releasing gem versions

Use GitHub Actions for releasing gems, with our shared publish workflow and the ALPHAGOV_RUBYGEMS_API_KEY secret. For builds with extra needs (e.g. the npm build step in govuk_publishing_components), copy and adapt the shared workflow.

Contact a GOV.UK GitHub Owner to grant your repository access to the secret.

Enforcing the release of new gem versions

Code changes are often merged into gems without the version being bumped. This leads to changes not being released quickly and sometimes piling up. To prevent that, we have a workflow that runs whenever a PR is open on our gems that checks if the user has bumped the gem version and updated the changelog. See the example of using the shared gem-bump-checker workflow in your project.

Automatically releasing patch-level versions

Use the shared autorelease workflow and the GOVUK_CI_GITHUB_API_TOKEN secret to automatically raise a PR to perform a patch-level version bump if the gem has unreleased changes, and all of those changes were authored by Dependabot. See the example of using the shared autorelease-rubygem workflow in your project. You should ensure it runs after the automatic dependency upgrades happened.

After a developer approves and merges that PR, the publish-rubygem workflow (if present) will automatically publish the next release to Rubygems.

Unreleased gem Slack alerts

We have a weekly check that alerts on team’s Slack channels when there are unreleased changes in their gem repositories.

Ruby version compatibility

Ensure gems are compatible with all supported minor Ruby versions, specifying the minimum minor Ruby version in the gemspec file. For example: spec.required_ruby_version = ">= 3.1".

Do not specify a patch (or “tiny”) Ruby version unless there is a particular issue with a Ruby patch release.

The .ruby-version file should be the same minor version level as the required_ruby_version in the gemspec, it is typically the most recent patch version. For example: spec.required_ruby_version >= "3.1" would correlate to a .ruby-version of 3.1.4.

When Ruby versions reach end-of-life (typically April) we update gems to drop support for that Ruby version and update the .ruby-version files to the next supported version. For example, when Ruby 2.7 reached end of life, we dropped 2.7 from the test matrices and we updated the .ruby-version file to be the most recent release of the 3.0 branch, which in March 2023 was 3.0.5 (see example).

We should then release the updated gem as a minor version. In the past, our policy was to release as a major version, but this was superfluous given that the change is low risk (Dependabot shouldn’t even raise a PR unless the upstream app is on a supported Ruby version). It also limited our ability to benefit from the automated workflows agreed in RFC-156, which apply only to patch and minor version upgrades. Note that patch versions are generally reserved only for bug fixes.