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.
Time to bump the version:
-
git checkout main && git pull origin main -
git checkout -b bump-faker-to-[VERSION] -
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
- Merge the PR, wait for CI to be green
- Publish the draft release you just created
Build and Publish the release
Once the PR containing the version bump and the CHANGELOG update is merged, and the release is published, we can build the gem:
-
Fetch the changes again with
git checkout main && git pull origin main && git fetch --tags -
Checkout the tag created when you published the release. For example:
git checkout tags/[VERSION] -b [VERSION] -
Run
bundle install -
Build the gem by running
gem build -o faker-[VERSION].gem faker.gemspec- Make sure to read the output to ensure the version matches the one you’re expecting.
- Run the tests again and make sure the new code is included
-
Push the gem to Rubygems by running:
gem push faker-[VERSION].gem - The output should say something as “The push was successful”.
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 release 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.