DEV Community

Cover image for How to release a new gem version
Thomas Hareau for Doctolib Engineering

Posted on • Updated on

How to release a new gem version

At Doctolib, we proudly maintain and develop the gem safe-pg-migrations, which makes migrations safer. Once in a while, after each relevant update, we release a new version.

The process is easy, but not well documented. I usually rely on my bash history to remember the different steps, but today, history | grep "gem push" gave me an empty result. So I decided that a blog post was more reliable than a self-deleting history.

The process presented below is the same for creating or updating your gem. In the example below, we use safe-pg-migrations and 1.2.0 as examples, they will need to be adapted to fit your needs.

Be sure of what you are going to publish.

Before starting the release process, you need to make sure the code you are about to publish is working as expected.

Have a look at the git history, make sure you are updated with the latest version of the main branch. Launching the tests is also a good idea.

Bump the version of the gem

First: update the version. It is specified in the gemspec file. You will need to open it with an editor:

vim safe-pg-migrations.gemspec
Enter fullscreen mode Exit fullscreen mode

And then update the version definition:

  s.version = '1.2.0'
Enter fullscreen mode Exit fullscreen mode

When choosing the new version, remember to follow the semantic versioning policies.

The version is also duplicated into Gemfile.lock. You can only update the CHANGELOG, if you maintain one.

Once the version is bumped, you can commit the changes:

git commit -m "v1.2.0"
git push
Enter fullscreen mode Exit fullscreen mode

Tag the new release

Once the version is updated, even if non-necessary, it is good to create a new tag. To do so, in your terminal, execute:

git tag -a v1.2.0 -m "Changelog..."
git push origin v1.2.0
Enter fullscreen mode Exit fullscreen mode

Tags are useful because they help other developers to see exactly which version of the code is associated to which version.
Every release can be fetched with git tag.
A specific version can be checked-out with git checkout v1.2.0.
Tags will also be listed in a specific page on GitHub, highlighting each release.

Publish the new release to RubyGem

Now the version was bumped and tagged, you can now proceed by publishing it to RubyGem.

First, you need to build a .gem file:

gem build safe-pg-migrations
Enter fullscreen mode Exit fullscreen mode

Once created, the file can be finally published. If you haven't done it already, you will need to create an account at

gem push safe-pg-migrations-1.2.0.gem
Enter fullscreen mode Exit fullscreen mode

This last step will take a few seconds to complete. You should receive an email shortly after, confirming that a new release was published.

Congratulation, you have published a new version of your gem!

If you find any most effective way to release, make sure to let us know in the comments!

Cover picture by Peps'

Top comments (2)

psychoslave profile image

Neat, clear and work perfectly. I laughed at the "uh how do I do that again?" introduction, which is exactly the question that led me here.

Also, that's nice the the post didn't skip the git tag step. kudo!

fwuensche profile image
Flavio Wuensche

Nice! That's useful. I'm pretty sure there's a rake release command available, but it's been so long I can't recall how it works. Might be worth taking a look at it too :)