Need to release a new Gem version but not sure how? Or are you just curious about how releasing a gem works? Then, this post is for you.
Whether you want to release a new version of a gem to RubyGems or are just curious about how it works, this post is for you.
I’ve learned how to do it this way and I just follow the script. The fear of messing up and causing issues for millions of users is big so I just stick to this script.
Update: I actually messed up on two releases! I still can’t know exactly what happened. I suspect it was because I did the release from the forked repository instead of the main repository. I didn’t event notice it until someone opened an issue on faker asking about it.
I made a mistake and to my surprise, the world didn’t end. Better yet: I have learned a safer way to make a release. This post is now updated to correctly publish a gem release.
Releasing a gem to RubyGems
Using faker-ruby as an example, let’s walk through a new release:
1 - Draft a release on GitHub
In the repository, go to the Releases page and create a new one. Then:
- Click on “Generate release notes”
- Edit the generated release notes as you see fit (optional)
- Save the release as a draft
-
Set the release tag when prompted - it should match the bumped gem version (e.g.:
v4.0.0)
2 - Create a new branch to bump the gem version
It’s really important to do this step in the main (upstream) repository instead of a fork. If you have the authorization to run a release, you certainly have the access to create tags on the main repository.
After you checked out the main remote branch, let’s do an example release for faker-ruby version 4.0.0:
-
git checkout main && git pull origin main -
git checkout -b bump-faker-to-v4.0.0. -
Update the gem version on
lib/faker/version.rb -
Run
bundle install - Update the CHANGELOG. I usually copy the generated ones from the draft release and edit them.
- Open a PR with the changes
- Publish the draft release
Build and Publish the draft release
Once the PR is merged, we can build the gem:
-
Fetch the changes again with
git checkout main && git pull origin main -
Checkout the tag created when you published the release. For example:
git checkout tags/v4.0.0 -b v4.0.0 -
bundle install -
Build the gem by running
gem build -o faker.gem faker.gemspec - Run the tests again and make sure the new code is included
-
Push the gem to Rubygems by running:
gem push faker.gem
And voila! If you have 2FA enabled (highly recommended!), you’ll be prompted to add the one-time password when running the push command.
Once it’s done, check out the gem on Rubygems: https://rubygems.org/gems/faker
Every gem has different release guidelines. I like to write a small message in the Changelog/Release notes about the new release, especially when there are breaking changes.
Guidelines and Resources for Releasing a Ruby Gem
If you’re looking for guidelines inspiration, check out factory bot’s RELEASING document.
Note: it’s now possible to automate parts of this process. Take a look at Trusted Publishing.
But even if you can automate it, it’s always good to know what the automation does anyway, so I hope you found this post useful.
See you on RubyGems.