Modernize deprecation-tracking.md for next_rails v1.5.0

Replace the ~25-line manual Ruby merge script (obsolete as of v1.5.0)
with the parallel-CI-native pattern:

- `node_index:` option on `track_rspec` / `track_minitest`. Can be
  passed explicitly (`node_index: ENV["CI_NODE_INDEX"]`) or
  auto-detected from standard CI env vars (`CIRCLE_NODE_INDEX`,
  `BUILDKITE_PARALLEL_JOB`, `SEMAPHORE_JOB_INDEX`, `CI_NODE_INDEX`).
- `deprecations merge --delete-shards` CLI command for the fan-in
  step that combines per-node shards into the canonical shitlist.
- `DeprecationTracker.merge_shards(path, delete_shards: true)`
  programmatic form for custom CI flows.
- `--next` flag for handling the next-Rails shitlist separately.

The three-phase CI workflow (save per node → merge once → compare per
node) is documented with runnable examples. Platform-specific env var
mapping covers CircleCI, Buildkite, GitLab CI, Semaphore, and generic
CI.

Also adds:
- Minimum `next_rails >= 1.5.0` callout at the top of Step 2, plus
  an updated Limitations note.
- "Last-resort fallback" section at the bottom with
  `bundle exec rspec 2>&1 | grep 'DEPRECATION WARNING' | sort -u`
  for apps where `DeprecationTracker` won't configure (loses
  structure, compare mode, and regression gating — use the tracker
  when possible).
- `deprecations merge --delete-shards` row in the Quick Reference.

Preserves: Why This Matters, silenced-deprecations detection
(Step 1), custom-deprecation-behavior approach for Minitest/parallel-fork
and older Rails (Step 3, all four Rails version variants retained),
Limitations, Maintenance, Quick Reference.

Implements plan §12.

Author: JuanVqz

dual-boot/references/deprecation-tracking.md

@@ -6,7 +6,7 @@
 
 ## Why This Matters
 
-Deprecation warnings are your roadmap during a Rails upgrade — they tell you exactly what will break in the next version. If deprecations are silenced, you're flying blind. Before setting up dual-boot, you must ensure deprecation warnings are visible and tracked.
+Deprecation warnings are your roadmap during a Rails upgrade. They tell you exactly what will break in the next version. If deprecations are silenced, you're flying blind. Before setting up dual-boot, you must ensure deprecation warnings are visible and tracked.
 
 ---
 
@@ -17,16 +17,16 @@ Check these files for silenced deprecations:
 ### Check `config/environments/test.rb`
 
 ```ruby
-# BAD — deprecations are invisible
+# BAD (deprecations are invisible)
 config.active_support.deprecation = :silence
 
-# BAD — all deprecation behaviors disabled (Rails 7.0+)
+# BAD (all deprecation behaviors disabled, Rails 7.0+)
 config.active_support.report_deprecations = false
 ```
 
 ### Check `config/environments/development.rb`
 
-Same patterns as above — `:silence` or `report_deprecations = false`.
+Same patterns as above: `:silence` or `report_deprecations = false`.
 
 ### Check for Global Silencing
 
@@ -60,19 +60,21 @@ If any of these are silencing deprecations, fix them before proceeding with the
 
 The `next_rails` gem includes `DeprecationTracker` which captures all deprecation warnings during test runs and saves them to a file. This gives you a complete inventory without stopping on the first failure (unlike `:raise`).
 
+> **Minimum `next_rails` version: 1.5.0** (released 2026-04-02). The parallel-CI-aware `node_index:` option and the `deprecations merge` CLI require v1.5.0. If your Gemfile currently pins an older version, update it before proceeding.
+
 ### Setup
 
-Ensure `next_rails` is in your Gemfile at the **root level** (not inside a `group` block):
+Ensure `next_rails` is in your Gemfile at the **root level** (not inside a `group` block), with the version constraint:
 
 ```ruby
 # Gemfile
-# MUST be at root level — not in :development or :test group
-gem 'next_rails'
+# MUST be at root level, not in :development or :test group
+gem 'next_rails', '>= 1.5.0'
 ```
 
 Then configure your test runner.
 
-**RSpec** — in `spec/spec_helper.rb` (or `spec/rails_helper.rb`):
+**RSpec**, in `spec/spec_helper.rb` (or `spec/rails_helper.rb`):
 
 ```ruby
 RSpec.configure do |config|
@@ -85,7 +87,7 @@ RSpec.configure do |config|
 end
 ```
 
-**Minitest** — in `test/test_helper.rb`:
+**Minitest**, in `test/test_helper.rb`:
 
 ```ruby
 DeprecationTracker.track_minitest(
@@ -95,19 +97,19 @@ DeprecationTracker.track_minitest(
 )
 ```
 
-- **`shitlist_path`** — where to save/read the deprecation inventory (required, no default)
-- **`mode`** — defaults to `save` so it always tracks
-- **`transform_message`** — strips the Rails root path from messages so the shitlist is portable across environments
+- **`shitlist_path`**: where to save/read the deprecation inventory (required, no default)
+- **`mode`**: defaults to `save` so it always tracks
+- **`transform_message`**: strips the Rails root path from messages so the shitlist is portable across environments
 
 ### Save the Deprecation Shitlist
 
-Run the test suite with `DEPRECATION_TRACKER=save` to collect all deprecation warnings (substitute your project's test command — e.g. `bundle exec rspec`, `bin/rails test`, `bin/test`):
+Run the test suite with `DEPRECATION_TRACKER=save` to collect all deprecation warnings (substitute your project's test command, e.g. `bundle exec rspec`, `bin/rails test`, `bin/test`):
 
 ```bash
 DEPRECATION_TRACKER=save bundle exec rspec
 ```
 
-This generates `spec/support/deprecation_warning.shitlist.json` — a JSON file listing every unique deprecation warning found during the run.
+This generates `spec/support/deprecation_warning.shitlist.json`, a JSON file listing every unique deprecation warning found during the run.
 
 > **Note:** Make sure the directory for `shitlist_path` exists before running.
 
@@ -117,55 +119,116 @@ Once you have a shitlist, run with `DEPRECATION_TRACKER=save` after fixing depre
 
 ### Workflow
 
-1. `DEPRECATION_TRACKER=save bundle exec rspec` — generates initial shitlist
+1. `DEPRECATION_TRACKER=save bundle exec rspec` generates the initial shitlist
 2. Review the shitlist to understand the scope of deprecations
 3. Fix one category of deprecation (e.g., `update_attributes`)
-4. `DEPRECATION_TRACKER=save bundle exec rspec` — updates the shitlist (it should shrink)
+4. `DEPRECATION_TRACKER=save bundle exec rspec` updates the shitlist (it should shrink)
 5. Repeat until the shitlist is empty
 6. Commit the shitlist file so the team tracks progress together
 
 ### CI with Parallel Test Execution
 
-`DeprecationTracker` does not natively support parallel execution. When CI splits tests across multiple nodes/containers (e.g., CircleCI parallelism, parallel_tests gem), each node only sees its subset of deprecations. You need to collect and merge the results.
+Starting with `next_rails` v1.5.0, `DeprecationTracker` has native support for parallel CI. When CI splits tests across multiple nodes or containers (CircleCI parallelism, Buildkite, GitLab, Semaphore, GitHub Actions matrix), each node writes its own shard file. A one-off merge step fans the shards back into the canonical shitlist.
 
-**Strategy: Save per-node, merge after**
+#### Configure `node_index:`
 
-1. On each CI node, run with `DEPRECATION_TRACKER=save` as normal
-2. Each node produces its own `spec/support/deprecation_warning.shitlist.json`
-3. After all nodes finish, collect and merge the shitlist files:
+Pass a `node_index:` value to `track_rspec` or `track_minitest`. When set, the tracker writes to `<shitlist_path>.node-<index>.json` instead of the canonical file, so parallel nodes don't clobber each other.
 
-```bash
-# Example merge script (run after all parallel nodes complete)
-# Collects shitlist JSON files from each node and merges them
+You can pass `node_index:` explicitly, or omit it and rely on auto-detection from standard CI environment variables:
 
-require 'json'
+| CI platform | Env var auto-detected |
+|---|---|
+| CircleCI | `CIRCLE_NODE_INDEX` |
+| Buildkite | `BUILDKITE_PARALLEL_JOB` |
+| GitLab CI | `CI_NODE_INDEX` |
+| Semaphore | `SEMAPHORE_JOB_INDEX` |
+| Generic | `CI_NODE_INDEX` |
 
-shitlists = Dir.glob("node-*/spec/support/deprecation_warning.shitlist.json")
-merged = {}
+**RSpec** with explicit `node_index:`:
 
-shitlists.each do |file|
-  data = JSON.parse(File.read(file))
-  data.each do |key, values|
-    merged[key] ||= []
-    merged[key] = (merged[key] + values).uniq
+```ruby
+RSpec.configure do |config|
+  if ENV["DEPRECATION_TRACKER"]
+    DeprecationTracker.track_rspec(
+      config,
+      shitlist_path: "spec/support/deprecation_warning.shitlist.json",
+      mode: ENV.fetch("DEPRECATION_TRACKER", "save"),
+      node_index: ENV["CI_NODE_INDEX"],
+      transform_message: -> (message) { message.gsub("#{Rails.root}/", "") }
+    )
   end
 end
+```
 
-File.write("spec/support/deprecation_warning.shitlist.json", JSON.pretty_generate(merged))
+If your CI sets one of the env vars in the table above, you can drop the `node_index:` argument entirely and let auto-detection handle it.
+
+**Minitest** with the same pattern:
+
+```ruby
+DeprecationTracker.track_minitest(
+  shitlist_path: "test/support/deprecation_warning.shitlist.json",
+  mode: ENV.fetch("DEPRECATION_TRACKER", "save"),
+  node_index: ENV["CI_NODE_INDEX"],
+  transform_message: -> (message) { message.gsub("#{Rails.root}/", "") }
+)
+```
+
+#### Three-phase CI workflow
+
+**Save phase** (each parallel node writes a shard):
+
+```bash
+DEPRECATION_TRACKER=save CI_NODE_INDEX=$NODE bundle exec rspec <subset>
 ```
 
-The exact collection mechanism depends on your CI setup:
-- **CircleCI**: Use `persist_to_workspace` / `attach_workspace` to gather shitlists from parallel containers
-- **GitHub Actions**: Use `upload-artifact` / `download-artifact` across matrix jobs
-- **parallel_tests gem**: Each process writes to the same filesystem, so you can glob the results directly
+Each node produces a file like `spec/support/deprecation_warning.shitlist.node-0.json`, `...node-1.json`, etc.
+
+**Merge phase** (runs once after all nodes finish, with shards gathered into one workspace):
+
+```bash
+deprecations merge --delete-shards
+```
 
-> **Tip:** Run the initial `DEPRECATION_TRACKER=save` locally (non-parallel) to generate the first complete shitlist. Use the parallel merge strategy in CI for ongoing regression checks.
+This fans all shards into the canonical `spec/support/deprecation_warning.shitlist.json` and removes the per-node files. To merge the next-Rails shitlist (the shards produced when running under the next Rails version in dual-boot), pass `--next`:
+
+```bash
+deprecations merge --next --delete-shards
+```
+
+For custom flows, call the programmatic form directly:
+
+```ruby
+DeprecationTracker.merge_shards(
+  "spec/support/deprecation_warning.shitlist.json",
+  delete_shards: true
+)
+```
+
+**Compare phase** (each parallel node compares its subset against the merged canonical file):
+
+```bash
+DEPRECATION_TRACKER=compare CI_NODE_INDEX=$NODE bundle exec rspec <subset>
+```
+
+The shard/canonical split means compare mode works per-node without false positives: each node only checks deprecations it actually emits, and the canonical shitlist already contains every deprecation from every node.
+
+#### Gathering shards between phases
+
+The exact mechanism to move shards from save-phase nodes into the merge job depends on your CI:
+
+- **CircleCI**: use `persist_to_workspace` in each parallel container, `attach_workspace` in the merge job
+- **GitHub Actions**: use `upload-artifact` from each matrix job, `download-artifact` in the merge job
+- **Buildkite**: use pipeline artifacts (`buildkite-agent artifact upload` / `download`)
+- **GitLab CI**: use job artifacts with `dependencies:` in the merge job
+- **parallel_tests gem (single host)**: each process writes to the same filesystem, so the merge step can run immediately without any artifact shuffle
+
+> **Tip:** Run the initial `DEPRECATION_TRACKER=save` locally without `node_index:` to generate the first complete canonical shitlist. Use the parallel sharded workflow in CI for ongoing regression checks.
 
 ### Limitations
 
-- **Not compatible with `minitest/parallel_fork`** — use standard minitest or RSpec
-- **No native parallel support** — requires manual merge when using CI parallelism (see above)
-- **Supports RSpec (`track_rspec`) and Minitest (`track_minitest`)** — other frameworks require manual integration
+- **Not compatible with `minitest/parallel_fork`.** Use standard Minitest, RSpec, or the custom deprecation behavior approach below.
+- **Requires `next_rails` >= 1.5.0** for native parallel CI support. Older versions need a manual merge script.
+- **Supports RSpec (`track_rspec`) and Minitest (`track_minitest`).** Other frameworks require manual integration.
 
 ---
 
@@ -197,7 +260,7 @@ config.active_support.deprecation = :log
 ```ruby
 # config/initializers/custom_deprecation_behavior.rb
 ActiveSupport::Deprecation.behavior = ->(message, callstack, deprecation_horizon, gem_name) {
-  # Deprecations you've already fixed — raise if they reappear
+  # Deprecations you've already fixed, raise if they reappear
   disallowed = [
     "update_attributes",
     /before_filter/,
@@ -277,4 +340,17 @@ After completing the upgrade:
 | Current behavior | `grep -rn "active_support.deprecation" .` |
 | Custom behaviors | `grep -rn "Deprecation.behavior" .` |
 | Save deprecation inventory | `DEPRECATION_TRACKER=save bundle exec rspec` |
+| Merge parallel shards | `deprecations merge --delete-shards` |
 | Existing warnings | `bundle exec rspec 2>&1 \| grep "DEPRECATION WARNING"` |
+
+---
+
+## Last-resort fallback
+
+If `DeprecationTracker` won't install or configure on your app (rare, see Limitations), you can capture deprecations by tailing the test log:
+
+```bash
+bundle exec rspec 2>&1 | grep "DEPRECATION WARNING" | sort -u
+```
+
+This loses structure, compare mode, and regression gating. Use `DeprecationTracker` when possible.