jam-cloud/upgrade-plan/MIGRATION.md

Migration Plan: Step 1

Goal: Establish a baseline and attempt the first major leap: Upgrading the shared ruby library to Ruby 3.2.2.

Phase 1: Verification (The "Before" State)

Before changing anything, we must confirm the current environment works as expected on this machine.

1. Verify Web Boot:

   • Command: cd web && bin/start_mx
   • Expectation: Rails server starts on port 3000.
   • Action: Stop server (Ctrl+C) once "Listening on..." appears.

2. Verify Shared Lib Tests:

   • Command: cd ruby && BUNDLE_GEMFILE=Gemfile.alt bundle _1.17.3_ exec rspec
   • Note: We use Gemfile.alt and Bundler 1.17.3 because that's what web/bin/start_mx suggests is the "working" configuration on this machine.
   • Expectation: Tests run (pass or fail, but they run).

Phase 2: The Upgrade (The "After" State)

We will target the ruby directory first. It is the foundation. If ruby doesn't work on Ruby 3.2, nothing else will.

1. Target: Ruby 3.2.2
2. Files to Change: ruby/Gemfile and ruby/Gemfile.alt
3. Changes:
   • Update ruby "..." directive to ruby "3.2.2".
   • Remove hard pins on ancient gems (e.g., nokogiri '1.10.10', json '1.8.6').
   • Update pg gem to remove OS-specific pins.
4. Execution:
   • Command: cd ruby && rbenv local 3.2.2 && bundle install
   • Note: We will use the modern Bundler provided with Ruby 3.2.2, not 1.17.3.
5. Verification:
   • Command: bundle exec rspec
   • Expectation: Dependencies resolve, and tests run.

Rollback Plan

If we get stuck, we can simply git checkout ruby/Gemfile* to revert to the working state.