All Case Studies Design Development Interviews Our Way Project Management

Maintain Your Gems Up-to-date With Netguru's Mini Guide

All gems must be kept up to date. The most important reason is to avoid security vulnerabilities, but new releases also improve speed, provide compatibility with newer versions of other libraries and often new features. This task gets harder as your Gemfile gets bigger, but the strategies below will help you ensure a smooth upgrade experience.

But first, let's introduce semantic versioning.

What is semantic versioning?

Semantic versioning is three dot-separated digits included in the gem version (it’s used for a lot of other software, too). It looks as follows:

>   The version number is of the form: MAJOR.MINOR.PATCH, where you increment the:

>   MAJOR version when you make incompatible API changes,

>   MINOR version when you add functionality in a backwards-compatible manner, and

>   PATCH version when you make backwards-compatible bug fixes.

from semver.org.

As a quick example, given Rails in version 4.2.6 one can deduce that:

  • it will have API changes incompatible with Rails version 3, so upgrading must be done with extreme caution
  • it has some extra functionality over Rails 4.1 but is very likely to still work, since backward compatibility is ensured
  • it has some very minor bug fixes in relation to Rails 4.2.5 and will definitely work in a backward compatible manner

With this knowledge you should be able to estimate difficulty of any given update.

Update one gem at at time

It’s tempting to just execute `bundle update` and update a whole bunch of gems at once. However, this may cause a lot of issues. Most gems depend on other gems to work properly and these may also need to be updated which can cause your app to behave in unexpected ways; there’s even the possibility of a circular dependency preventing the batch update from finishing.

It’s also a lot easier to read through the documentation, in particular the changelog section, when updating a single gem. If you add gems one by one to your new application, it’s even more natural not to update them all at once in an already established codebase.

Instead pick one and update it.

It’s common to choose the biggest or the most important gem from your technology stack and start with it, digging your way down into utility gems. Updating a Big Boss Gem may mean small updates along the way.

Bump checklist

Once you choose which gem to update, follow these steps:


  1. Choose a gem you want to update.
  2. Go to its homepage or repository and read the changelog. This step can sometimes be omitted with a patch version, but it’s worth reading nevertheless. Be especially aware of all other gems which may be affected by the update.
  3. If you are making a major or minor version update - make a plan for migration. Remember that the same process you’re going through on your local development machine will need to be duplicated on staging and production machines as well.
  4. Make an update on your local machine and follow your list of tasks from the previous point.
  5. Commit your changes. Remember to always commit changes from Gemfile.lock and, if applicable, changes from Gemfile at the same time. Consider adding all required migrations and tasks as well.This way reverting it will be easier.
  6. Proceed with updating the staging and production servers. Revert your work if necessary.
  7. Do not hesitate to stop deployment and revert your commit if things go south.
  8. If everything’s OK - then run your tests. Fix code, if necessary.

Congratulations. Now your code should be up to date! As mentioned earlier, adding new gems to your stack should be thought of as adding a new big feature, especially when it brings you all the hassle of maintenance like this.

New Call-to-action
Follow Netguru
Join our Newsletter

Scaling SaaS
Need a successful project?
Estimate project or contact us