How to release a new gem version
Tags: ruby, opensource, github, tutorial
Published: 2021-03-18 15:13:45

At Doctolib, we proudly maintain and develop the gem [safe-pg-migrations](https://github.com/doctolib/safe-pg-migrations), which [makes migrations safer](https://medium.com/doctolib/stop-worrying-about-postgresql-locks-in-your-rails-migrations-3426027e9cc9). 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:

```sh
vim safe-pg-migrations.gemspec
```

And then update the version definition: 

```
  s.version = '1.2.0'
```

When choosing the new version, remember to follow the [semantic versioning policies](https://guides.rubygems.org/patterns/#semantic-versioning).

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: 

```sh
git commit -m "v1.2.0"
git push
```

## 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:

```sh
git tag -a v1.2.0 -m "Changelog..."
git push origin v1.2.0
```

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](https://github.com/doctolib/safe-pg-migrations/releases), 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:

```sh
gem build safe-pg-migrations
```

Once created, the file can be finally published. If you haven't done it already, you will need to create an account at https://rubygems.org/users/new.

```sh
gem push safe-pg-migrations-1.2.0.gem
```

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'](https://www.facebook.com/people/Peps/100063638581693/)