Thought I would share the general procedure I have come up with that I have learnt with upgrading Monolithic Ruby on Rails apps. The focus allows the code to still accept changes/features while the upgrade is happening which could take a few months to complete.

These phased steps can be used to upgrade large rails application for minor/major rails releases in more manageable pieces where everyone working on the code has to get involved and making it visible on your “agile” board. Even though thought has been put into this process, please make sure to always use your better judgement when applying the various guidelines.

Requirements

• Decent Test Coverage (> 95% recommended) (Good Feature Coverage helps too)
• CI
• Version Control
• Create an Epic Story named something like “Upgrade to Rails x.x” on your Story/Ticket System

It’s not recommended that you skip a version when attempting to upgrade, this could make things harder to do the actual upgrade in small steps. ie If you want to upgrade from Rails 4.1 to Rails 5.1, it might be better to upgrade Rails 4.1 to Rails 4.2 and then repeat the process for upgrading Rails 4.2 to Rails 5.0.

Phase General Flow

This is the general flow each phase follows

• Create a Story/Ticket on your board
• Attempt it
• on Success
  • merge code in
  • share new steps with the team
  • mark story Done (completed)
  • move to the next Phase
• on Failure
  • Merge in as much as you can
  • create required refactoring stories
  • mark story Done (“Won’t fix”/incomplete/attempted)
  • Try again when all refactor stories are done

Phase 1: Second Gemfile

Goal: Once this phase is done, it helps ensures that from here onwards no incompatible gems version are updated/added that don’t bundle with both Rails versions.

Phase 2: Config working on both versions

Goal: Have the application loading on both versions with updated config. One merged any new changes will have to make sure the app boots in both versions.

Phase 3: CI running tests on both versions (Mark failures as pending)

Goal: tests that fail on next version marked as pending. Once merged any new code will have to work in both versions.

Phase 4: CI running tests on both versions (passing on upgrade as well)

Goal: Have all the tests passing. Once merged the test suite will always be green for both versions

Phase 5: Staging Environment

Goal: Get a staging environment up and running.

Phase 6: Staging Testing

Goal: Confirm the app works in the new version.

Phase 7: Live Testing/Making the switch

Goal: Start running on the new version.

Phase 8: Clean up old version

Goal: Remove any specific logic around the old version.

I’ll be doing follow-up posts that will an example of what the steps of each phase could look like.