HOWTO dev bundle_and_gemset_update

HOW-TO: bundle & gemset update

Any sub-project using goggles_db should include the update_engine.sh script, with which you can re-synch the engine with its latest version.

Updating anything else beside the goggles_db gem with a simple bundle update may yield various inconsistencies & failures. We advise you to try to update or change the bundle using a dedicated branch on your repo and using a new named Gemset made with RVM.

Create the new branch with git and prepare the container Gemset following the steps below.

Assuming you are targeting, for example, ruby-2.6.6 as interpreter:

$> rvm list known
$> rvm install 2.6.6
$> rvm gemset create goggles7-rails6
$> rvm gemset use 2.6.6@goggles7-rails6
$> gem i bundler

In case the gemset that you want to use for the updated branch has been already created but has resulted in failed updates or too many regression errors, you may want to try a different and more stable set of gems.

For that, you can just empty the gemset and retry to build the bundle. Otherwise, skip step #3 below.

Prepare your project for the bundle change:

1. Remove the Gemfile.lock from the project & edit the Gemfile specifying the new versions for the gems you're willing to update.

2. Make sure the Ruby interpreter version of the Gemset is reflected correctly in all these files:

• Gemfile (typically, around line 6, if the ruby statement is included)
• .versions.conf
• .ruby-version
• rubocop.yml, look for TargetRubyVersion at the beginning of the file
• any additional CI or Docker build configuration present should reflect the Ruby version for its base image during the build steps (but these usually can wait until you're sure the targeted version has a 💚 test suite run)

3. Clear the Gemset if needed:

   $> rvm gemset empty 2.6.6@goggles7-rails6

4. Enter the project root; if the .versions.conf has a ruby-bundle-install=true in it, RVM will automatically rebuild your bundle.

   If you're including goggles_db in the Gemfile, the bundle install is deemed to fail because the gem embeds the test DB image which can't be downloaded automatically by git-lfs because of the nested dependency.

   Don't worry, and carry on.

   So, if the bundle halts or if you're just not using .versions.conf with the auto-bundle install, run manually:

   $> GIT_LFS_SKIP_SMUDGE=1 bundle install

   ...And see the results.

5. If this new Gemset bundle succeeds, either run a full test suite run with guard or - at least - check it with rubocop & rspec to see if there are any major regression errors.

All 💚? Then you're done! :-)