The following article is specific to Software Services by Scientist.com 📖. While the specifics are for my day job, the general approach is something I find useful to share.
In this playbook article we’ll list the steps to take when upgrading. We’ll also mention some of our conventions and how to build a checklist from those conventions.
The Four Tasks of the Apocalypse
There are four primary tasks when updating a gem:
- Determine breaking changes between current version and updated version.
- Review any local overrides to see if they relate to the gem being updated.
- Update the code-base
- Test the changes
The Review and local overrides and Update the code-base can be done in either order. However, I recommend checking first reviewing overrides and making a list.
The reason being that you’ve done the work on reviewing the breaking changes; so that is fresh (and documented). You can then go into the code-base and with that salient context look for changes made that decorate/override the gem’s behavior.
Determine Breaking Changes
A quick, albeit not reliable litmus on whether there might be breaking changes in the gem is to look at the change in version numbers. Assuming the gem uses Semantic Versioning, if you changing minor or patch versions then the likelihood of a breaking change is smaller.
Warning: Rails notoriously does not adhere to Semantic Versioning; and in most cases it is a judgment call by the gem maintainers whether there are breaking version changes.
For major version changes, you will need to be more vigilant.
In all cases, reading the release notes should get you a good understanding, albeit potentially overwhelming, of what has changed. Note all of the breaking changes.
You may need to clarify with client that breaking changes are acceptable. Note: in this case the break was client facing. Added both the question and confirmation to Update Bulkrax to v4 · Issue #211 · scientist-softserv/britishlibrary.
Review Any Local Overrides
Ideally, the code base that you are updating has followed Overrides with Decorators and Class Eval | Wiki.js. You’ll want to look for two changes:
- Files ending in `_decorator.rb`
- Files that contain “OVERRIDE” as a comment
First cd into the project directory.
The following assumes you have Ripgrep 📖 installed. You can past the following into your shell:
find . -type f -name "*_decorator.rb" | awk '{ print "- [ ] " $1 }' > overrides_checklist.md ;
rg "^\s*#.*OVERRIDE" -i --files-with-matches | awk '{ print "- [ ] " $1 }' >> overrides_checklist.md
The first line finds the Ruby files that ends in decorator.rb, converts each line into a markdown style checkbox, then creates and writes to overrides_checklist.md.
The following line finds all Ruby style OVERRIDE comments (using a case insensitive match). It then converts it to markdown checkbox, and appends to the newly created overrides_checklist.md.
Work your way through that checklist, making notes and removing unrelated values. As a happy bonus, if you continue with that checklist, writing notes, you can upload that to the comments of your pull request.
Update the Code Base
To update the Gemfile, you’ll likely need to run bundle inside the web container.
- Pull the most recent changes to main
- Created and checked out my feature branch
- Started docker (via `sc up`)
- With the instance running, I updated the Gemfile
- Then ran `docker compose exec web bundle`
At this point, git showed that I had changes to my Gemfile and Gemfile.lock; all as expected.
Test the Changes
You then want to take the results of your override review and any upgrade notes provided by the gem and start testing and making corresponding changes.
You can test locally at first. Both running the tests locally and by firing up the app and testing the changes noted in the release.
Eventually you’ll want to push that code and deploy it to a staging server. You’ll want to coordinate with the team to inform them that you are needing to test changes on staging.
Conclusion
Along the way, remember note taking is your friend as is version control.