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
And then update the version definition:
s.version = '1.2.0'
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
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
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
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.
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'
Top comments (2)
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!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 :)