docs: the legacy API is removed in 2.1, not 3.0

docs/UPGRADING.md

@@ -167,7 +167,7 @@ about the old namespaces; the third is about the driver features 2.1 removes.
 The first time a process touches *any* hookable legacy API, you get a single line:
 
 ```
-[snap_diff deprecation] This process uses the v1 `Capybara::Screenshot*` / `CapybaraScreenshotDiff*` API. It still works in 2.x and is REMOVED in 3.0 -- see docs/UPGRADING.md for the SnapDiff replacements. Silence with `SnapDiff.silence_deprecations = true` or SNAP_DIFF_SILENCE_DEPRECATIONS=1. (shown once per process)
+[snap_diff deprecation] This process uses the v1 `Capybara::Screenshot*` / `CapybaraScreenshotDiff*` API. It still works in 2.0 and is REMOVED in 2.1 -- see docs/UPGRADING.md for the SnapDiff replacements. Silence with `SnapDiff.silence_deprecations = true` or SNAP_DIFF_SILENCE_DEPRECATIONS=1. (shown once per process)
 ```
 
 It fires once and never again, whichever door you came through:
@@ -177,7 +177,7 @@ It fires once and never again, whichever door you came through:
 - `include Capybara::Screenshot` / `include Capybara::Screenshot::Diff`
 
 It exists because most of the v1 surface **cannot** warn per use, so without it a 2.x app could
-be entirely silent right up to the bare `NameError` it would get on 3.0.
+be entirely silent right up to the bare `NameError` it would get on 2.1.
 
 #### 2. Per-constant warnings — one line per lazily shimmed constant
 
@@ -295,7 +295,7 @@ Capybara::Screenshot::Diff.stub_const(:AVAILABLE_DRIVERS, []) { ... }
 SnapDiff::Drivers.stub_const(:AVAILABLE_DRIVERS, []) { ... }
 ```
 
-**`SnapDiff::Config::MAPPING` is gone.** It split in two: `SnapDiff::Config::SETTINGS` (the setting names, no legacy knowledge) and `SnapDiff::LegacyShims::CONFIG_MAPPING` (which legacy holder each name hangs off). If you referenced `MAPPING` — iterating settings in a test helper, say — use `SETTINGS`; `CONFIG_MAPPING` is `@api private` and disappears in 3.0 with the rest of the v1 surface.
+**`SnapDiff::Config::MAPPING` is gone.** It split in two: `SnapDiff::Config::SETTINGS` (the setting names, no legacy knowledge) and `SnapDiff::LegacyShims::CONFIG_MAPPING` (which legacy holder each name hangs off). If you referenced `MAPPING` — iterating settings in a test helper, say — use `SETTINGS`; `CONFIG_MAPPING` is `@api private` and disappears in 2.1 with the rest of the v1 surface.
 
 ---
 

lib/snap_diff/deprecation.rb

@@ -38,11 +38,11 @@ module Deprecation
     # the v1 surface cannot warn per use -- the config accessors are plain
     # delegators and the eager aliases never reach const_missing -- so
     # without this a 2.x app is completely silent right up to the bare
-    # NameError it gets on 3.0. Deliberately generic and once per process:
+    # NameError it gets on 2.1. Deliberately generic and once per process:
     # an actionable signal, not per-call stderr noise.
     MIGRATION_NOTICE =
       "[snap_diff deprecation] This process uses the v1 `Capybara::Screenshot*` / " \
-      "`CapybaraScreenshotDiff*` API. It still works in 2.x and is REMOVED in 3.0 -- " \
+      "`CapybaraScreenshotDiff*` API. It still works in 2.0 and is REMOVED in 2.1 -- " \
       "see docs/UPGRADING.md for the SnapDiff replacements. Silence with " \
       "`SnapDiff.silence_deprecations = true` or SNAP_DIFF_SILENCE_DEPRECATIONS=1. " \
       "(shown once per process)"

test/legacy/errors_alias_test.rb

@@ -2,7 +2,7 @@
 
 require "test_helper"
 # The shared harness loads canonical entry points only, so a legacy-surface
-# test pulls in the v1 entry itself -- the require goes with the file in 3.0.
+# test pulls in the v1 entry itself -- the require goes with the file in 2.1.
 require "capybara_screenshot_diff"
 
 # ADR-008 step 2: the error classes live in SnapDiff (snap_diff/errors);
@@ -14,7 +14,7 @@
 # warnings, so these tests double as proof the aliases stay warning-free.
 #
 # LEGACY SURFACE (test/legacy/, see the Rakefile): deleted with lib/capybara*
-# in 3.0. The hierarchy assertions that outlive the aliases moved to
+# in 2.1. The hierarchy assertions that outlive the aliases moved to
 # test/unit/errors_test.rb.
 class ErrorsAliasTest < ActiveSupport::TestCase
   # old constant path => new constant path

test/legacy/legacy_config_accessors_test.rb

@@ -2,7 +2,7 @@
 
 require "test_helper"
 # The shared harness loads canonical entry points only, so a legacy-surface
-# test pulls in the v1 entry itself -- the require goes with the file in 3.0.
+# test pulls in the v1 entry itself -- the require goes with the file in 2.1.
 require "capybara_screenshot_diff"
 
 # LEGACY SURFACE (test/legacy/, see the Rakefile).

test/legacy/legacy_config_default_timing_test.rb

@@ -7,7 +7,7 @@
 # LEGACY SURFACE (test/legacy/, see the Rakefile).
 #
 # The v1 half of config_default_timing_test.rb. Two claims, both about the
-# old entry points and the old accessor view, both deleted in 3.0:
+# old entry points and the old accessor view, both deleted in 2.1:
 #
 # 1. every legacy entry point produces the SAME require-time defaults and
 #    the same freezing/liveness behaviour as the canonical ones -- proved by

test/legacy/legacy_forwarders_test.rb

@@ -3,7 +3,7 @@
 require "test_helper"
 require "open3"
 # The shared harness loads canonical entry points only, so a legacy-surface
-# test pulls in the v1 entry itself -- the require goes with the file in 3.0.
+# test pulls in the v1 entry itself -- the require goes with the file in 2.1.
 require "capybara_screenshot_diff"
 require "capybara_screenshot_diff/static"
 

test/legacy/legacy_namespace_deprecation_test.rb

@@ -13,7 +13,7 @@
 # namespace_forwarding_test.rb; this file pins only the warning behavior.
 #
 # LEGACY SURFACE (test/legacy/, see the Rakefile): deleted with lib/capybara*
-# and snap_diff/deprecation.rb in 3.0.
+# and snap_diff/deprecation.rb in 2.1.
 class LegacyNamespaceDeprecationTest < ActiveSupport::TestCase
   # Documented exceptions that stay EAGER (real constants, never warn):
   # - Os / DSL: advertised entry-point constants, probed with

test/legacy/legacy_tree_is_alias_only_test.rb

@@ -7,12 +7,12 @@
 # lib/capybara/ and lib/capybara_screenshot_diff/ are the v1 compatibility
 # surface. Every unit of behaviour has moved to lib/snap_diff/, so what is
 # left must be nothing but requires, namespace reopening, constant aliases
-# and one-line forwarders. If that stays true, dropping v1 support in 3.0 is
+# and one-line forwarders. If that stays true, dropping v1 support in 2.1 is
 # a deletion; the moment real logic lands back in these trees it becomes a
 # refactor. This test fails the second that happens, naming the file.
 #
 # LEGACY SURFACE (test/legacy/, see the Rakefile): deleted with the trees it
-# scans in 3.0. Its mirror image, core_tree_has_no_legacy_deps_test.rb,
+# scans in 2.1. Its mirror image, core_tree_has_no_legacy_deps_test.rb,
 # guards what 3.0 KEEPS and so stays in test/unit/.
 class LegacyTreeIsAliasOnlyTest < ActiveSupport::TestCase
   LIB = Pathname.new(__dir__).join("../../lib").expand_path

test/legacy/namespace_forwarding_test.rb

@@ -2,7 +2,7 @@
 
 require "test_helper"
 # The shared harness loads canonical entry points only, so a legacy-surface
-# test pulls in the v1 entry itself -- the require goes with the file in 3.0.
+# test pulls in the v1 entry itself -- the require goes with the file in 2.1.
 require "capybara_screenshot_diff"
 
 # Every old-namespace constant touched by the ADR-004 v2 file-tree move
@@ -13,7 +13,7 @@
 # that always returns false.
 #
 # LEGACY SURFACE (test/legacy/, see the Rakefile): deleted with lib/capybara*
-# in 3.0, when there is no old namespace left to forward.
+# in 2.1, when there is no old namespace left to forward.
 class NamespaceForwardingTest < ActiveSupport::TestCase
   # This file's whole purpose is resolving the old names, so silence the
   # shims' deprecation warnings here (the suite-wide guard in test_helper

test/legacy/snap_diff_deprecation_test.rb

@@ -6,7 +6,7 @@
 
 # LEGACY SURFACE (test/legacy/, see the Rakefile): SnapDiff::Deprecation is
 # the channel that announces the v1 shims, so snap_diff/deprecation.rb and
-# this file are deleted together with lib/capybara* in 3.0.
+# this file are deleted together with lib/capybara* in 2.1.
 class SnapDiffDeprecationTest < ActiveSupport::TestCase
   def setup
     SnapDiff::Deprecation.reset!
@@ -186,7 +186,7 @@ def capture_warnings
 
     assert_equal 1, out.scan(NOTICE_MARKER).size, "expected exactly one migration notice, got:\n#{out}"
     assert_includes out, "docs/UPGRADING.md"
-    assert_includes out, "REMOVED in 3.0"
+    assert_includes out, "still works in 2.0 and is REMOVED in 2.1"
     assert_includes out, "SNAP_DIFF_SILENCE_DEPRECATIONS"
   end
 

test/unit/canonical_suite_has_no_legacy_refs_test.rb

@@ -86,7 +86,7 @@ class CanonicalSuiteHasNoLegacyRefsTest < ActiveSupport::TestCase
     # every canonical entry point). It names the deletion set and the edits
     # by construction, and asserts its own gate line can reject an intact
     # tree -- it cannot do that without spelling the doomed names.
-    "unit/deletion_3_0_test.rb" => [
+    "unit/legacy_deletion_test.rb" => [
       '["snap_diff.rb", %(require "snap_diff/legacy_shims"), nil],',
       '%(require "capybara_screenshot_diff/minitest"),',
       'gate << "SnapDiff.start is still defined" if SnapDiff.respond_to?(:start)',

test/unit/config_default_timing_test.rb

@@ -21,7 +21,7 @@
 # Canonical entry points only, read through SnapDiff.config only. The v1
 # entry points and the "both surfaces agree" half re-run these same scripts
 # from test/legacy/legacy_config_default_timing_test.rb, which is deleted
-# with the v1 trees in 3.0.
+# with the v1 trees in 2.1.
 class ConfigDefaultTimingTest < ActiveSupport::TestCase
   ENTRY_POINTS = %w[
     snap_diff

test/unit/core_tree_has_no_legacy_deps_test.rb

@@ -3,7 +3,7 @@
 require "test_helper"
 
 # The REVERSE of legacy_tree_is_alias_only_test.rb, and the other half of
-# what makes 3.0 a `git rm`.
+# what makes the 2.1 deletion a `git rm`.
 #
 # That test proves the v1 trees hold no logic. This one proves the canonical
 # core does not reach BACK into them -- which is the half that actually
@@ -12,8 +12,8 @@
 # `CapybaraScreenshotDiff::*` constant, deleting lib/capybara* leaves a core
 # that no longer loads.
 #
-# Scope: everything the 3.0 deletion KEEPS. Files that are themselves part of
-# the deletion set (DELETED_IN_3_0 below) live under lib/snap_diff/ only
+# Scope: everything the 2.1 deletion KEEPS. Files that are themselves part of
+# the deletion set (DELETED_WITH_LEGACY_TREES below) live under lib/snap_diff/ only
 # because the generator for the v1 surface has to be code, and the v1 trees
 # have to stay alias-only -- they are legacy by design and go with it.
 #
@@ -27,17 +27,17 @@
 class CoreTreeHasNoLegacyDepsTest < ActiveSupport::TestCase
   LIB = Pathname.new(__dir__).join("../../lib").expand_path
 
-  # Deleted alongside lib/capybara* in 3.0: these files exist to BUILD the
+  # Deleted alongside lib/capybara* in 2.1: these files exist to BUILD the
   # v1 compatibility surface (const_missing shims, the legacy config
   # accessor generator, the deprecation channel that announces both).
-  DELETED_IN_3_0 = %w[
+  DELETED_WITH_LEGACY_TREES = %w[
     snap_diff/legacy_shims.rb
     snap_diff/deprecation.rb
   ].freeze
 
   CORE_FILES = (
     [LIB.join("snap_diff.rb")] + Dir[LIB.join("snap_diff/**/*.rb")].map { |p| Pathname.new(p) }
-  ).sort.reject { |file| DELETED_IN_3_0.include?(file.relative_path_from(LIB).to_s) }.freeze
+  ).sort.reject { |file| DELETED_WITH_LEGACY_TREES.include?(file.relative_path_from(LIB).to_s) }.freeze
 
   # A require of anything in the v1 trees: `capybara/screenshot/...`,
   # `capybara_screenshot_diff...`, `capybara-screenshot-diff`. Plain
@@ -62,7 +62,7 @@ class CoreTreeHasNoLegacyDepsTest < ActiveSupport::TestCase
   #
   # EMPTY. It was seeded with all 64 core->legacy edges that existed the day
   # the gate was written, and every one of them is gone. Keep it empty: an
-  # entry is a decision to keep a core->legacy edge across the 3.0 deletion,
+  # entry is a decision to keep a core->legacy edge across the 2.1 deletion,
   # so it needs a written reason here AND an ADR-008 update -- never just a
   # red build turned green.
   ALLOWED = {}.freeze

test/unit/drivers_test.rb

@@ -42,7 +42,7 @@ class DriversTest < ActiveSupport::TestCase
   # Ported from namespace_forwarding_test (test/legacy/), which was the only
   # place pinning this: it asserted the v1 LOADED_DRIVERS constant is the
   # same object as this hash and that a registration through it shows up
-  # here. The v1 half dies in 3.0; the canonical half -- .loaded is ONE
+  # here. The v1 half dies in 2.1; the canonical half -- .loaded is ONE
   # memoized hash, mutated in place, so a driver registered into it stays
   # registered (Utils.find_driver_class_for caches through it) -- must not.
   test ".loaded is a single hash mutated in place, so registrations stick" do

test/unit/errors_test.rb

@@ -5,7 +5,7 @@
 # The canonical half of what used to be errors_alias_test.rb: the shape of
 # the SnapDiff error hierarchy itself, which outlives the v1 aliases. The
 # `CapybaraScreenshotDiff::*` alias half stayed behind in
-# test/legacy/errors_alias_test.rb and goes with the v1 trees in 3.0.
+# test/legacy/errors_alias_test.rb and goes with the v1 trees in 2.1.
 class ErrorsTest < ActiveSupport::TestCase
   test "error hierarchy is preserved" do
     assert_operator SnapDiff::ExpectationNotMet, :<, SnapDiff::Error

test/unit/image_compare_test.rb

@@ -77,7 +77,7 @@ class ImageCompareTest < ActiveSupport::TestCase
 
   test "#initialize with :auto driver raises error when no drivers available" do
     # Canonical stubbing point since the detected-drivers list moved to
-    # SnapDiff::Drivers (3.0 readiness). The legacy
+    # SnapDiff::Drivers (2.1 readiness). The legacy
     # Capybara::Screenshot::Diff::AVAILABLE_DRIVERS is now an eager
     # same-object ALIAS of this constant, so stubbing the old name only
     # rebinds the alias and no longer reaches the core.

test/unit/deletion_3_0_test.rb → test/unit/legacy_deletion_test.rb

@@ -6,7 +6,7 @@
 require "fileutils"
 require "unit/support_load_probe_test" # single source of truth for the canonical entry-point tables
 
-# THE 3.0 DELETION, ACTUALLY RUN.
+# THE 2.1 DELETION, ACTUALLY RUN.
 #
 # legacy_tree_is_alias_only_test.rb and core_tree_has_no_legacy_deps_test.rb
 # are STATIC proxies for one claim: `git rm` the v1 surface and the gem still
@@ -24,10 +24,10 @@
 # tmpdir. The subprocess is isolated from bundler as well (see #probe), but
 # that isolation is precisely the thing that silently stopped working last
 # time -- the gate line is what notices when it does.
-class Deletion30Test < ActiveSupport::TestCase
+class LegacyDeletionTest < ActiveSupport::TestCase
   PROJECT_ROOT = Pathname.new(File.expand_path("../..", __dir__))
 
-  # The 3.0 `git rm`, verbatim from the Rakefile's header comment (minus
+  # The 2.1 `git rm`, verbatim from the Rakefile's header comment (minus
   # test/legacy, which this test does not load).
   DELETED = %w[
     capybara
@@ -43,11 +43,11 @@ class Deletion30Test < ActiveSupport::TestCase
   # reworded, the edit must go red here rather than silently not applying and
   # leaving the probe to fail somewhere confusing.
   EDITS = [
-    # The one line in the canonical entry point that 3.0 drops.
+    # The one line in the canonical entry point that 2.1 drops.
     ["snap_diff.rb", %(require "snap_diff/legacy_shims"), nil],
     # The new gem name's Bundler entry point is KEPT, repointed off the v1
     # umbrella. It matches neither gate's file glob, so this is the only
-    # thing that checks its post-3.0 shape at all.
+    # thing that checks its post-2.1 shape at all.
     ["snap_diff-capybara.rb",
       %(require "capybara_screenshot_diff/minitest"),
       %(require "snap_diff/integrations/minitest")]
@@ -86,7 +86,7 @@ class Deletion30Test < ActiveSupport::TestCase
     end
   RUBY
 
-  test "every canonical entry point loads and keeps its surface after the 3.0 deletion" do
+  test "every canonical entry point loads and keeps its surface after the 2.1 deletion" do
     in_deleted_tree do |tree|
       failures = ENTRY_POINTS.filter_map do |entry, methods|
         probe(tree, <<~RUBY)
@@ -99,15 +99,15 @@ class Deletion30Test < ActiveSupport::TestCase
       end
 
       assert_empty failures, <<~MSG
-        `git rm` of the v1 surface breaks canonical entry point(s) -- 3.0 is a
+        `git rm` of the v1 surface breaks canonical entry point(s) -- 2.1 is a
         refactor, not a deletion, until these load:
 
         #{failures.join("\n")}
       MSG
     end
   end
 
-  test "every canonical entry point defines its advertised constants after the 3.0 deletion" do
+  test "every canonical entry point defines its advertised constants after the 2.1 deletion" do
     in_deleted_tree do |tree|
       failures = SupportLoadProbeTest::CANONICAL_ADVERTISED_CONSTANTS.filter_map do |entry, constants|
         probe(tree, <<~RUBY)
@@ -154,22 +154,22 @@ def copy_lib_to(dir)
     File.realpath(File.join(dir, "lib"))
   end
 
-  # Yields the path to a lib/ with the 3.0 deletion applied.
+  # Yields the path to a lib/ with the 2.1 deletion applied.
   def in_deleted_tree
     Dir.mktmpdir("snapdiff_deleted") do |dir|
       tree = copy_lib_to(dir)
 
       DELETED.each do |path|
         target = File.join(tree, path)
-        assert File.exist?(target), "3.0 deletion set names #{path}, which does not exist"
+        assert File.exist?(target), "2.1 deletion set names #{path}, which does not exist"
         FileUtils.rm_rf(target)
       end
 
       EDITS.each do |file, line, replacement|
         target = Pathname.new(File.join(tree, file))
         source = target.read
 
-        assert_includes source, line, "3.0 edit for #{file} no longer matches the file"
+        assert_includes source, line, "2.1 edit for #{file} no longer matches the file"
         target.write(source.sub(line + "\n", replacement ? replacement + "\n" : ""))
       end
 

test/unit/snap_diff_config_test.rb

@@ -6,7 +6,7 @@
 # same storage -- LegacyShims::CONFIG_MAPPING's completeness and the
 # write-through-either-surface round trips -- lives in
 # test/legacy/legacy_config_accessors_test.rb and is deleted with the v1
-# trees in 3.0. What is here has to keep standing on its own after that.
+# trees in 2.1. What is here has to keep standing on its own after that.
 class SnapDiffConfigTest < ActiveSupport::TestCase
   def config
     SnapDiff.config

test/unit/snap_diff_test.rb

@@ -6,7 +6,7 @@
 class SnapDiffTest < ActiveSupport::TestCase
   # The ImageCompare alias claim and the v1-shaped SnapDiff.start / .configure
   # pair live in test/legacy/legacy_forwarders_test.rb -- both are v1 surface
-  # and go with it in 3.0.
+  # and go with it in 2.1.
   test ".compare returns the same kind of result as Diff.compare, forwarding options" do
     result = SnapDiff.compare(
       TEST_IMAGES_DIR / "a.png",

test/unit/support_load_probe_test.rb

@@ -27,7 +27,7 @@
 # CapybaraScreenshotDiff session surface, and the eager user-facing
 # constants under the old names -- are probed the same way from
 # test/legacy/legacy_entry_point_probe_test.rb, which is deleted with the v1
-# trees in 3.0.
+# trees in 2.1.
 class SupportLoadProbeTest < ActiveSupport::TestCase
   SKIP = {
     # "support/example" => "why it cannot load bare"
@@ -69,7 +69,7 @@ class SupportLoadProbeTest < ActiveSupport::TestCase
   #
   # SnapDiff.start is absent for a different reason: it is defined in
   # snap_diff/legacy_shims.rb and yields the two v1 config holders, so it
-  # cannot outlive them (#235). A CANONICAL gate demanding a method 3.0
+  # cannot outlive them (#235). A CANONICAL gate demanding a method 2.1
   # deletes is a gate that fails the day the deletion lands -- which is
   # exactly what it did. `.start` keeps its coverage on the legacy side:
   # test/legacy/legacy_forwarders_test.rb asserts what it yields and that it
@@ -79,7 +79,7 @@ class SupportLoadProbeTest < ActiveSupport::TestCase
   ].freeze
 
   # snap_diff-capybara is the canonical gem's Bundler entry point, so it is
-  # probed here rather than with the v1 ones: 3.0 keeps it (repointed at
+  # probed here rather than with the v1 ones: 2.1 keeps it (repointed at
   # snap_diff/integrations/minitest), it just stops carrying the
   # CapybaraScreenshotDiff surface.
   CANONICAL_ENTRY_POINTS = {