Polish release_gate_geotiff.rst for maintainer use (#2345 PR 3, closes #2381)

[brendancol]

Closes #2381. Part of epic #2345 (PR 3 of the release-gate doc polish wave).

What changed

• Added a "How a maintainer runs this gate" section at the top of
  docs/source/reference/release_gate_geotiff.rst. It covers the
  pytest selection / marker for the gate suite, skip-handling guidance
  (GPU absent, optional codecs, COG validator opt-in), and the tier
  promote / demote decision rule that a maintainer follows when a row
  passes or regresses.
• Added an Epic column to every list-table so each row links back to
  its owning epic (Promote COG support to ready/stable with compliance and parity gates #2286, GeoTIFF release hardening: define and lock down supported VRT contract #2321, Epic: GeoTIFF release contract and feature tiering #2340, Epic: GeoTIFF correctness and backend parity release gate #2341, Epic: Conservative VRT support contract for GeoTIFF release #2342, or Epic: GeoTIFF remote/source safety hardening #2344). The
  six epic anchors are collected in an "Owning epics" section at the
  bottom of the page.
• Fixed tier mismatches against SUPPORTED_FEATURES. reader.allow_rotated
  and reader.allow_unparseable_crs move from advanced to
  experimental to match the runtime constant. Replaced freeform
  tier strings ("rejected at writer boundary", "rejected") with the
  parent feature's tier where the row is a sub-gate of an existing
  feature (the COG tile-layout pre-flight rows now sit under
  writer.cog, and VRT mixed-band nodata sits under the nodata
  fail-closed contract).
• Replaced the stale "Placeholder PR cross-references" block at the
  bottom of the file with an "Owning epics" section that lists each
  epic title alongside its anchor.

Out of scope

• No new regression tests. The acceptance text states "if a gate row
  points at a missing test, file a follow-up issue rather than write
  the test here". I checked every test path referenced in the file
  and all 99 cited tests exist, so no follow-up was needed.
• geotiff.rst's tier table is untouched per the issue scope.

Test plan

• pytest xrspatial/geotiff/tests/test_release_gate_2321.py xrspatial/geotiff/tests/test_supported_features_tiers_2137.py passes (24 passed, 1 xpassed).
• Every test path referenced in the doc exists on disk.
• Every row tier is one of stable / advanced / experimental /
  internal_only and matches SUPPORTED_FEATURES where the feature
  key appears in that constant.
• The new "how to run" section names the pytest invocation, the
  skip-handling rule, and the promote / demote decision rule.
• RST parses cleanly (docutils round-trip; Sphinx build runs in CI).

[brendancol]

PR Review: Polish release_gate_geotiff.rst for maintainer use (#2345 PR 3, closes #2381)

Docs-only PR. Algorithm / backend / performance parts of the review template don't apply. I checked doc accuracy and the acceptance criteria from #2381.

Blockers

None.

Suggestions

• release_gate_geotiff.rst:23-27: the top note names the six owning epics but skips #2345, which is the epic this PR is part of. Add a line pointing at #2345 so the file traces back to its own parent.
• release_gate_geotiff.rst:312-315: the reader.http row still says (see ``#2321`` sub-PR 5). The "Placeholder PR cross-references" section that gave that label meaning is gone (good), so the reference now dangles. Replace sub-PR 5 with #2326 or drop the parenthetical.
• release_gate_geotiff.rst:326-335 and 336-342: the SSRF and per-tile byte-cap rows are stable while their parent rows (reader.http, reader.http_cog) are advanced. The mismatch is intentional but reads as drift. One sentence in "How a maintainer runs this gate" noting that sub-gates can carry a stricter tier than their parent row would head off a future audit flag.
• geotiff_release_contract.md:93-94 (out of scope for this PR): the companion doc still tiers reader.allow_rotated and reader.allow_unparseable_crs at advanced, which now conflicts with this PR's experimental. File a follow-up so the two files don't drift.

Nits

• release_gate_geotiff.rst:46-51: the -k release_gate filter assumes every release-gate test file is named test_release_gate_*.py. Worth one ls check; if any cited file does not match, the recommended pytest invocation under-runs the gate.
• release_gate_geotiff.rst:79-82: the "newly-passing xfail" guidance says re-tier the row but does not say "remove the xfail marker in the same commit". Worth spelling out.
• release_gate_geotiff.rst:172: row title eager / dask parity (sub-gate of ``reader.dask``) uses a parenthetical, while rows like reader.windowed -- shifted-transform parity use a dash. Pick one form so the row index scans.

What looks good

• All three required pieces of the "how to run" section are present: pytest invocation, skip handling, promote/demote rule.
• Every row has all five required pieces (feature, tier, acceptance, test, epic).
• The two SUPPORTED_FEATURES tier mismatches (reader.allow_rotated, reader.allow_unparseable_crs) are fixed.
• 99/99 cited test paths exist on disk. No missing-test follow-up needed.

Checklist

• Doc parses (docutils; local Sphinx env unrelated)
• Every row has acceptance + test path + epic + tier
• Every tier value matches SUPPORTED_FEATURES
• Every cited test exists on disk
• "How a maintainer runs this gate" covers the three required pieces
• geotiff.rst tier table untouched
• No new tests added (scope: file follow-up if needed)
• [n/a] Algorithm / backend correctness (docs-only)
• [n/a] README matrix (docs-only)

[brendancol]

PR Review (round 2): Polish release_gate_geotiff.rst (#2345 PR 3, closes #2381)

Re-reviewed after ac8e979c. Every actionable item from round 1 was addressed in-PR. Round 1 deferral (geotiff_release_contract.md tier drift) is tracked in #2389.

Blockers

None.

Suggestions

None.

Nits

• release_gate_geotiff.rst:328: the new #2326 reference resolves to a merged PR rather than an issue. The other inline #... references in the file all point at issues. Not a bug (the link works), but if you want full consistency, swap for #2323 (the parent issue that #2326 closed) and leave the prose unchanged. Optional; ignore if you'd rather keep the direct PR pointer.

What looks good

• The "doc-readiness epic that owns this checklist itself is #2345" line at line 27-28 closes the round-1 trace-back gap.
• The new "A note on sub-gate rows" subsection explains the intentional tier-mismatch (SSRF row stable while parent reader.http is advanced) cleanly. Future audit passes will not file this as drift.
• Row title reader.dask -- eager / dask parity now matches the dash convention used elsewhere. The redundant (sub-gate) parentheticals are gone.
• The "newly-passing xfail" guidance now says exactly what to do: remove the marker in the same commit.

Checklist

• Round-1 blockers / suggestions / nits addressed in-PR (or deferred to filed follow-up)
• Every gate row still has acceptance + test path + epic + tier
• Every tier value still matches SUPPORTED_FEATURES
• Every cited test still exists on disk
• RST parses cleanly (docutils round-trip)