geotiff: golden corpus phase 4 PR 2, baseline-update docs (#1930)#2044
Merged
Conversation
Adds the contributor-facing page that explains how to bless intentional pixel-level baseline changes for the golden corpus. * ``docs/source/contributing/index.rst`` -- new contributing section, only entry today is the corpus baselines page. * ``docs/source/contributing/golden_corpus_baselines.rst`` -- what a corpus failure means, how to bless an intentional baseline change, how to add a new fixture, and how to use the fast / slow split (phase 4 PR 1). * ``docs/source/index.rst`` -- toctree entry for the new section. This is the last PR in the #1930 plan. Closes out the phase 4 ops set.
* Add a note up front that the doc describes the system as of the full Phase 3 + Phase 4.1 PR set, so contributors do not chase a missing ``_marks.py`` while one of those PRs is still in flight. * Replace the ``\`` line-continuation in the per-fixture regeneration example with a single-line invocation; the backslash form is POSIX-shell-only and would fail in ``cmd.exe``. * Normalise file-path references to the full ``xrspatial/geotiff/tests/golden_corpus/<file>`` form where the text used the bare filename. * Cross-link the corpus ``README.md`` from the Fast / Slow section rather than repeat its content; the two pages have different audiences (test-tree contributor vs docs-site reader) and the cross-reference is the lightest way to keep them aligned.
This was referenced May 18, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Phase 4 PR 2 of the golden corpus plan in #1930 -- the last PR in the plan. Adds the contributor-facing page that explains how to bless intentional pixel-level baseline changes for the golden corpus.
Three files:
docs/source/contributing/index.rst: new top-level section. Currently has one entry (the corpus baselines page); future contributor docs land here.docs/source/contributing/golden_corpus_baselines.rst: the substance. Covers what a corpus test failure means, the workflow for blessing an intentional baseline change, the workflow for adding a new fixture, and how the fast / slow split (phase 4 PR 1, geotiff: golden corpus phase 4 PR 1, fast/slow split (#1930) #2043) interacts with the matrix.docs/source/index.rst: toctree entry for the new section.The page is intentionally workflow-driven rather than reference-style: every section ends with concrete shell commands a contributor would actually run.
Test plan
docutilsparses both new.rstfiles cleanly (no underline-too-short warnings, no broken role references beyond the expected:ref:/toctreeones that resolve under sphinx).sphinx.ext.extlinksis not configured indocs/source/conf.py;:gh-issue:would not resolve.Refs #1930. With this PR, the #1930 plan is fully landed: phases 1-2 already merged, phase 3 (six backend-wiring PRs: #2036, #2038, #2039, #2040, #2041, #2042) and phase 4.1 (#2043) open in parallel, and this PR closes phase 4.