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.