docs: the 2.0.0 CHANGELOG entry, for someone coming from 1.15.1

[pftg]

The [v2.0.0] section was written around #257 and has been overtaken by ten PRs. Three of its claims are now false, one repeats the shape of the beta2 defined? mistake, and the whole correctness story — the actual reason to upgrade — was missing.

Rewritten for the stated audience: someone on 1.15.1 for a year who never read a beta note. Lead with what they must do (nothing — the v1 names keep working), then what they gain, then what warns, then what 2.1 removes.

Claims that had gone false, and how I know

Claim in the tree	Check	Result
"Known limitations: fork-based parallel tests produce no HTML report … Fixed in 2.1"	Ran a Capybara+Minitest project under parallelize(workers: 2, threshold: 0) on 1.15.1, then on this master via path:	1.15.1: no report file, no summary line. master: one merged report + 4 verified, 4 changed, 0 new. Fixed in 2.0 (#266) — bullet removed
"a suite whose only contact with the v1 API is require "capybara_screenshot_diff/minitest" + include …Assertions still prints nothing"	Built exactly that suite, ran it on master	It does print the migration notice — #263 made the require doors warn. Section rewritten
"Two removals 2.0 cannot warn about … driver: as a setting"	Capybara::Screenshot::Diff.driver = :vips on master	Prints the removal line with a call site. #263 hooked the writer and the per-screenshot key. Table row added, paragraph corrected

The defined? trap, again

The silent-by-design list read … the error classes, ::VERSION, Os, Region, Reporters::Default, LOADED_DRIVERS, AVAILABLE_DRIVERS — a run of Capybara::Screenshot::Diff:: names with Os and Region sitting inside it. Probed on master:

Capybara::Screenshot::Os                    defined?="constant"  const_get=true
Capybara::Screenshot::Diff::Os              defined?=nil         const_get=false
Region                                      defined?="constant"  const_get=true
Capybara::Screenshot::Diff::Region          defined?=nil         const_get=false

Neither ::Diff::Os nor ::Diff::Region existed in 1.15.1 either (git show v1.15.1:lib/capybara/screenshot/diff/os.rb defines Capybara::Screenshot::Os; region.rb defines a top-level class Region). Now fully qualified, with the trap spelled out in "the five things that can actually break". ::Comparison added to match docs/UPGRADING.md.

New material (all verified)

• "Why upgrade: 1.15.1 had four ways to pass green while testing nothing" — fix: stop passing green when a screenshot has no committed baseline #255, fix: an inherited GIT_DIR silently redirected every baseline lookup #256, fix: libvips serves stale pixels when a screenshot is rewritten within the same second #254, fix: the HTML report survives Rails' fork-parallel test runs (#258) #266 — plus fix: never print a path or command that is not derived from live state (#260) #267's unfollowable CI message and the fail_if_new precedence change.
• Before/after failure message (feat: make the failure message legible #264), both transcripts taken from the same page rendered on 1.15.1 and on master, not reconstructed.
• The summary line (feat: the summary line counts what was verified, not just what was compared #261) — including the thing that would otherwise read as a missing feature: it comes from the HTML reporter, so it needs require "snap_diff/reporters/html". My first upgraded run printed no summary line at all until I added that require.
• The perf: stop decoding matching screenshots and re-spawning git per assertion #250/fix: concurrent callers each spawned their own git rev-parse #253 perf table, attributed to its harness, columns labelled before/after rather than 1.x/2.0 — I confirmed 1.15.1 runs the same two code paths (no byte-identical short-circuit in image_compare.rb#processed, no cache around rev-parse in diff/vcs.rb) but did not re-run that harness myself.
• The libvips fix is stated as guarded on libvips 8.15+, so a reader on an older libvips knows the bug is still theirs. REVALIDATE = Vips.at_least_libvips?(8, 15) ? {revalidate: true} : {}.
• The activesupport claim, which nobody had confirmed first-hand, reproduced verbatim: a non-Rails bundle on 1.15.1 dies with LoadError: cannot load such file -- active_support/core_ext/module/attribute_accessors at capybara_screenshot_diff/snap_manager.rb:4.

Semver

Stated plainly rather than buried: removing public API in 2.1 (a MINOR) is a deliberate departure from strict semver, and publishing the contract one release ahead is the mitigation.

Install pins: deliberately NOT unpinned

Every snippet stays on 2.0.0.beta3. ~> 2.0 resolves to nothing on rubygems today, so unpinning now ships instructions that hard-fail bundle install. docs/RELEASE_PREP.md already carries a precise, executable step to swap all five as part of the 2.0.0 push — I ran its grep and it finds exactly those five (README.md, CHANGELOG.md, docs/UPGRADING.md ×2, docs/migration-guide.md), so no change was needed there.

Placeholder

Record modes (record: :once / :none / :all) are an HTML comment marked PLACEHOLDER in the entry — invisible if it somehow ships, impossible to mistake for a description. RELEASE_PREP.md gains one checklist line (grep -n 'PLACEHOLDER' CHANGELOG.md) so it cannot go out unfilled.

Gates

mise x ruby@4.0.6 -- bundle exec rake test:unit → 651 runs, 1922 assertions, 0 failures.
mise x ruby@4.0.6 -- bundle exec standardrb lib test → 158 files, no offenses.

Docs only. version.rb, lib/snap_diff/config.rb and screenshot_matcher.rb untouched.

Summary by Sourcery

Rewrite the 2.0.0 release documentation to accurately guide 1.15.1 users through the upgrade and its migration path.

Enhancements:

• Rewrite the 2.0.0 changelog for users upgrading from 1.15.1, covering compatibility, upgrade benefits, migration warnings, breaking changes planned for 2.1, and known limitations.
• Document the major correctness, reporting, diagnostics, compatibility, and performance improvements delivered in 2.0.0.
• Clarify legacy API deprecation behavior, silent compatibility cases, and the specific changes that require migration.

Documentation:

• Add a release-preparation checklist item to detect unfilled changelog placeholders.

Summary by CodeRabbit

• Documentation
  • Expanded the v2.0.0 changelog with details on bug fixes, migration and deprecation behavior, validation and summary reporting, clearer failure messages, dependency loading, and parallel HTML report handling.
  • Added guidance for missing baselines, inherited environment variables, cache invalidation, explicit failure settings, require-time notices, deprecated drivers, and unrecognized options.
  • Documented planned removals in v2.1 and strengthened release checklist requirements.

[sourcery-ai]

Sorry @pftg, you have reached your weekly rate limit of 500000 diff characters.

Please try again later or upgrade to continue using Sourcery

[sourcery-ai]

Reviewer's Guide

This documentation-only PR replaces the stale 2.0.0 changelog entry with an evidence-backed upgrade guide for 1.15.1 users, accurately describing compatibility, correctness fixes, diagnostics, warnings, performance, dependencies, reporting, and the 2.1 migration contract; release preparation now explicitly checks for unfilled placeholders.

File-Level Changes

Change	Details	Files
Rewrote the 2.0.0 changelog as a migration guide for users upgrading directly from 1.15.1.	Leads with source compatibility and the concrete correctness reasons to upgrade. Documents four silent-success bugs, improved diagnostics, performance changes, dependency fixes, and report behavior. Corrects deprecation-warning coverage, future 2.1 removals, defined? namespace pitfalls, driver warnings, and SemVer implications. Adds verified before/after examples, benchmark context, libvips version caveat, install-pin rationale, and a visible record-modes placeholder. Updates added, changed, fixed, known-limitation, and unchanged sections while removing obsolete claims.	CHANGELOG.md
Added a release-readiness check to prevent placeholder content from shipping.	Adds a checklist command that finds unfilled placeholders in the changelog. Explains that each placeholder must be completed from the corresponding feature PR or removed.	docs/RELEASE_PREP.md

Possibly linked issues

• Create CODE_OF_CONDUCT.md #4: Links to ADR-004 because it documents and prepares the 2.0 release outcomes and migration contract described there.

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: fab57d3d-287f-4246-8ee1-e1e91f3100e5

📥 Commits

Reviewing files that changed from the base of the PR and between f1ceea9 and cafdf59.

📒 Files selected for processing (2)

• CHANGELOG.md
• docs/RELEASE_PREP.md

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

The changelog now documents 2.0.0 fixes, reporting behavior, dependency changes, deprecations, compatibility behavior, and planned 2.1 removals. The release checklist now requires resolving or removing all changelog placeholders.

Changes

Release documentation

Layer / File(s)	Summary
2.0.0 behavior and fix documentation CHANGELOG.md	Documents four silent failure fixes, missing-baseline handling, reporting changes, dependency-loading behavior, and corrected runtime behavior.
Deprecation and compatibility documentation CHANGELOG.md	Documents require-time notices, removed settings and APIs, legacy constant behavior, and planned 2.1 errors.
Release checklist validation docs/RELEASE_PREP.md	Adds a checklist step to resolve or remove every PLACEHOLDER entry in CHANGELOG.md.

Estimated code review effort: 2 (Simple) | ~10 minutes

Merge Risk: ⚪ Minimal · up to cafdf

This documentation-only change updates the 2.0.0 upgrade guidance and release checklist without changing runtime behavior; no actionable merge-blocking risk remains after normal checks and review.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the main change: updating the 2.0.0 changelog for users upgrading from 1.15.1.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0 files. (2 skipped: 2 unsupported.)
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/changelog-2-0-0

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}