WA-DOC-020: Refresh Rails 7.2 notes with current blockers

.github/workflows/ci.yml

@@ -297,7 +297,11 @@ jobs:
     - name: Bundle install
       id: bundle
       run: bundle install
-      continue-on-error: ${{ matrix.experimental }}
+      continue-on-error: true
+
+    - name: Bundler lockfile mismatch hint
+      if: steps.bundle.outcome != 'success' && !matrix.experimental
+      run: bash script/ci/bundler_lockfile_hint
 
     - name: Install system deps (docker-compose + ImageMagick)
       run: sudo apt-get update && sudo apt-get install -y docker-compose imagemagick
@@ -346,11 +350,14 @@ jobs:
         ruby-version: ${{ matrix.ruby-version }}
         bundler-cache: false
     - name: bundle install
-      run: |
-        bundle install || {
-          if [[ "${{ matrix.experimental }}" == "true" ]]; then
-            echo "::warning::bundle install failed on Ruby ${{ matrix.ruby-version }} (informational — experimental version)"
-            exit 0
-          fi
-          exit 1
-        }
+      id: bundle
+      continue-on-error: true
+      run: bundle install
+
+    - name: Bundler lockfile mismatch hint
+      if: steps.bundle.outcome != 'success' && !matrix.experimental
+      run: bash script/ci/bundler_lockfile_hint
+
+    - name: Warn on experimental bundle failures
+      if: steps.bundle.outcome != 'success' && matrix.experimental
+      run: echo "::warning::bundle install failed on Ruby ${{ matrix.ruby-version }} (informational — experimental version)"

docs/rails7-migration-patterns/rails-7-2-notes.md

@@ -1,73 +1,59 @@
-# Rails 7.2 forward-compatibility notes (Workarea)
+# Rails 7.2 appraisal notes (Workarea)
 
-> Issue: https://github.com/workarea-commerce/workarea/issues/761
-> Branch: `wa-forward-001-rails72-compat`
+Primary tracking:
 
-## Summary
+* Umbrella: https://github.com/workarea-commerce/workarea/issues/768
+* **Current bundler blocker (canonical):** https://github.com/workarea-commerce/workarea/issues/841
+  * Specific repro/details: https://github.com/workarea-commerce/workarea/issues/839
+  * Also impacts security snapshots (Brakeman / bundler-audit): https://github.com/workarea-commerce/workarea/issues/840
 
-Attempting to add a Rails 7.2 appraisal Gemfile currently **does not bundle** due to an explicit Rails version constraint in Workarea.
+## Summary
 
-**Current scope assessment:** **moderate**
+Rails 7.2 appraisal (`gemfiles/rails_7_2.gemfile`) currently **cannot bundle**.
 
-* Rationale: The immediate blocker is mechanical (relax gemspec constraints), but we can’t yet see downstream dependency/test failures until bundler resolves.
+This is **no longer** blocked by a Workarea Rails upper-bound constraint (e.g. `workarea-core` allows `rails < 7.3` as of current `next`).
 
-## Bundler result
+**The active blocker is the Mongoid dependency line:** `workarea-core` depends on `mongoid ~> 7.4`, and Mongoid 7.x constrains `activemodel < 7.1`, which makes Rails 7.1/7.2 unsatisfiable.
 
-Created `gemfiles/rails_7_2.gemfile`:
+## Repro
 
-```ruby
-# frozen_string_literal: true
+Rails 7.2 requires Ruby >= 3.1, and Workarea’s `.ruby-version` is currently **3.2.7**.
 
-eval_gemfile File.expand_path('../Gemfile', __dir__)
+```sh
+# Ensure you're using the repo Ruby (example uses rbenv)
+export PATH="$HOME/.rbenv/shims:$HOME/.rbenv/bin:$PATH" && eval "$(rbenv init - zsh)"
+rbenv shell 3.2.7
 
-gem 'rails', '~> 7.2.0'
+cd /path/to/workarea
+BUNDLE_GEMFILE=gemfiles/rails_7_2.gemfile bundle install
 ```
 
-Running `BUNDLE_GEMFILE=gemfiles/rails_7_2.gemfile bundle install` fails with:
+## Bundler failure (key excerpt)
+
+From #839:
 
 ```text
-Because every version of workarea-core depends on rails >= 6.1, < 7.2
-  and rails_7_2.gemfile depends on workarea-core >= 0,
-  rails >= 6.1, < 7.2 is required.
-So, because rails_7_2.gemfile depends on rails ~> 7.2.0,
-  version solving has failed.
+Because every version of workarea-core depends on mongoid ~> 7.4
+  and mongoid >= 7.3.4, < 8.0.7 depends on activemodel >= 5.1, < 7.1, != 7.0.0,
+  every version of workarea-core requires activemodel >= 5.1, < 7.1, != 7.0.0.
+Thus, every version of workarea-core is incompatible with rails >= 7.2.0.
 ```
 
-### Immediate blocker
-
-`workarea-core` (and likely other Workarea component gems) has an upper bound of **`rails < 7.2`**. Until that constraint is relaxed, we cannot get a lockfile or run CI to discover *actual* Rails 7.2 incompatibilities.
+## Intended path forward
 
-## Rails 7.2 changes to watch (from release notes / upgrade guide)
-
-Primary references:
-
-* https://edgeguides.rubyonrails.org/7_2_release_notes.html
-* https://edgeguides.rubyonrails.org/upgrading_ruby_on_rails.html#upgrading-from-rails-7-1-to-rails-7-2
+1. **Unblock bundling by upgrading Mongoid/ODM dependencies** to a version line compatible with Rails/ActiveModel 7.1 and 7.2.
+   * Canonical issue: https://github.com/workarea-commerce/workarea/issues/841
+2. Once Bundler resolves under `gemfiles/rails_7_2.gemfile`, run the test suite + verification tasks and triage failures.
 
-Notable items that could affect Workarea/apps:
+## Known follow-up failures (after bundling is restored)
 
-* **Ruby minimum version is now 3.1** (Workarea is already running Ruby 3.2.7 in this assessment, so this is fine).
-* **Active Job test behavior change**: in Rails 7.2, tests respect `config.active_job.queue_adapter` if explicitly set (previously some tests could still silently use the TestAdapter). If Workarea sets a non-test adapter in the test environment, or test assumptions relied on the implicit TestAdapter, expect failures.
-* **Active Job transactional enqueue behavior**: Rails 7.2 defers enqueuing jobs until after commit when enqueued inside an Active Record transaction, and drops jobs on rollback. (Workarea is Mongoid-based, but apps/plugins may use Active Record, and this can surface as behavior changes in mixed environments.)
-* **`alias_attribute` behavior change**: aliases bypass custom attribute methods and read raw DB value. (Quick scan: no `alias_attribute` usage found in Workarea itself.)
+These issues are expected to be relevant once the appraisal can bundle/run in CI:
 
-## Quick codebase scan
+* Rack::Cache constant load error in integration test: https://github.com/workarea-commerce/workarea/issues/787
+* Catalog slug caching test failure (Rails 7.2 / Mongoid 8): https://github.com/workarea-commerce/workarea/issues/788
+* User password reuse validation test failure (Rails 7.2 / Mongoid 8): https://github.com/workarea-commerce/workarea/issues/789
 
-A quick grep for some historically-deprecated patterns surfaced:
+## Rails 7.2 upstream references
 
-* `Rails.application.config.force_ssl` usage in:
-  * `storefront/app/mailers/workarea/storefront/application_mailer.rb`
-  * `storefront/app/helpers/workarea/storefront/navigation_helper.rb`
-
-This isn’t necessarily removed in 7.2, but it’s worth re-checking when the bundle resolves.
-
-## Follow-up work (recommended issues)
-
-1. Relax Rails upper bound in Workarea gemspecs (at least `workarea-core`) to allow bundler resolution with Rails 7.2.
-2. Once bundling succeeds: run Workarea test suite under Rails 7.2 and capture failures/regressions.
-3. Audit Workarea test configuration for `active_job.queue_adapter` expectations under Rails 7.2.
-
-## Open questions
-
-* After relaxing the Rails upper bound, do any dependency constraints (Mongoid, Sidekiq, etc.) prevent Rails 7.2 resolution?
-* What CI matrix (if any) should be updated to include a Rails 7.2 appraisal run?
+* https://edgeguides.rubyonrails.org/7_2_release_notes.html
+* https://edgeguides.rubyonrails.org/upgrading_ruby_on_rails.html#upgrading-from-rails-7-1-to-rails-7-2

script/ci/bundler_lockfile_hint

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# This helper is meant to run *only* when bundler (or ruby/setup-ruby's bundler-cache)
+# has failed.
+#
+# It re-runs bundler quietly and inspects the output for the common
+# frozen/deployment-mode lockfile mismatch case, then prints a high-signal
+# GitHub Actions annotation.
+#
+# Context: this repo commits .bundle/config with BUNDLE_FROZEN/BUNDLE_DEPLOYMENT true.
+# When Gemfile.lock is out of date, bundler refuses to proceed in CI.
+
+if ! command -v bundle >/dev/null 2>&1; then
+  echo "::error::Bundler is not available (cannot diagnose Gemfile.lock mismatch)."
+  exit 1
+fi
+
+log_file="${RUNNER_TEMP:-/tmp}/bundler-install.log"
+
+set +e
+bundle install >"$log_file" 2>&1
+status=$?
+set -e
+
+# If bundler unexpectedly succeeds on the re-run, just fail with a generic message
+# (the original failure is what we want to surface).
+if [[ $status -eq 0 ]]; then
+  echo "::error::Bundler previously failed, but succeeded when re-run. See logs above."
+  exit 1
+fi
+
+# Detect the lockfile mismatch / frozen mode case without dumping the full log.
+if grep -Eq \
+  "(You are trying to install in deployment mode after changing your Gemfile|You have added to the Gemfile|You have changed in the Gemfile|The dependencies in your Gemfile changed|Your lockfile is out of date)" \
+  "$log_file"; then
+  # Note: the message text is intentionally short/high-signal. We avoid pasting
+  # the full bundler output to keep CI logs readable.
+  cat <<'MSG'
+::error::Bundler is running in frozen/deployment mode and Gemfile.lock is out of date.
+Fix: run `bundle install`, commit the updated Gemfile.lock, and push.
+MSG
+  exit 1
+fi
+
+# Not the lockfile mismatch case.
+echo "::error::Bundler failed, but it does not look like a frozen-mode lockfile mismatch. See logs above."
+exit 1