GeoTIFF: add release gate / audit checklist (#2321 sub-task 6)

[brendancol]

Closes #2331. Refs #2321 (sub-task 6 of 6).

Summary

• Adds docs/source/reference/release_gate_geotiff.rst, a per-feature release checklist for the GeoTIFF module. Every row pairs a tier (stable / advanced / experimental / internal_only) with a one-line acceptance and at least one regression test path. Sections: local read/write, COG, HTTP/fsspec, nodata lifecycle, attrs contract, VRT supported subset, sidecar and overview interactions, GPU experimental paths, internal-only surfaces, and cross-cutting CI gates.
• Adds xrspatial/geotiff/tests/test_release_gate_2321.py, a meta-gate that keeps the checklist honest:
  • every cited test file exists on disk;
  • every promised SUPPORTED_FEATURES key (tiers stable or advanced) is named in the checklist prose, so a new public tier cannot ship without a row;
  • HTTP SSRF rejects loopback hosts for lowercase URLs (locked in today);
  • HTTP SSRF rejects loopback hosts for uppercase URLs (xfail until sub-PR 5 / Reject uppercase HTTP(S) schemes in geotiff URL dispatch (#2323) #2326 lands);
  • VRT rows resolve to non-empty test files.
• Wires the new page into docs/source/reference/index.rst and adds a .. seealso:: link from docs/source/reference/geotiff.rst so readers find the audit trail from the main GeoTIFF reference page.

Backend coverage

Docs and meta-tests only. No backend-specific code paths added.

Placeholders to fill in

The checklist cites sub-PRs 1 through 5 of #2321. Only sub-PR 5 has a real PR today (#2326); the rest are tracked under #2321 as (see #2321). Once each sub-PR lands, swap its placeholder for the real PR number both in release_gate_geotiff.rst and in the parent issue's tracking comment.

Test plan

• pytest xrspatial/geotiff/tests/test_release_gate_2321.py (4 passed, 1 xfailed)
• pytest xrspatial/geotiff/tests/test_supported_features_tiers_2137.py (still green; no regression)
• docutils parse of the new .rst succeeds with only the expected Sphinx-role notices (:data:, :class:, :ref:)

[brendancol]

PR Review: GeoTIFF: add release gate / audit checklist (#2321 sub-task 6)

Scope is documentation plus a meta-test that gates the doc against drift. No new kernels, no new dispatch, no new public API. The correctness / backend / performance checklist items are N/A. Findings focus on the doc-as-contract and the meta-test's failure modes.

Blockers

None.

Suggestions

1. xrspatial/geotiff/tests/test_release_gate_2321.py:153 -- the xfail(raises=Exception) is wider than it needs to be. Today the uppercase scheme path raises ValueError from fsspec (Protocol not known: HTTP). Narrow raises= to (ValueError, UnsafeURLError) so a future regression that produces a different exception class (RuntimeError, an OSError from a real socket dial, etc.) does not silently xfail. When sub-PR 5 / #2326 lands, the xfail flips to a pass and the test starts enforcing the UnsafeURLError promise.

2. docs/source/reference/release_gate_geotiff.rst:268 -- the HTTP SSRF defense row points at test_release_gate_2321.py for its only regression test, but the real SSRF rejection logic is already exercised by the SSRF suite (e.g. xrspatial/geotiff/tests/test_cog_http_*.py and the HTTP source tests). Citing only the meta-gate makes the row look thinly covered. Add the existing SSRF tests to the "Regression test" cell so a reader sees the depth of coverage.

3. xrspatial/geotiff/tests/test_release_gate_2321.py:62 -- _TEST_PATH_RE matches any xrspatial/geotiff/tests/<word>/<word>.py path, including non-test_ files like conftest.py. That is permissive but it would let a typo in the checklist (citing conftests.py) sneak by as long as the file exists. Tighten the regex to require a test_ prefix on the leaf name, or add a second assert that every cited file starts with test_.

Nits

1. docs/source/reference/release_gate_geotiff.rst:1 -- the title overline / underline length is exact now, but the section underlines below it (Local GeoTIFF read and write, etc.) use = and are sometimes longer than the title. Mixed style. Not a build error; just visually noisy in raw rst.

2. docs/source/reference/index.rst:18 -- new entry placed after geotiff_internals. Consistent with the existing flat-alphabetical-ish ordering. Could co-locate with geotiff instead for navigability, but the current placement is fine and matches the surrounding pattern.

3. xrspatial/geotiff/tests/test_release_gate_2321.py:96 -- _PROMISED_TIERS = {"stable", "advanced"} -- worth a one-line comment that experimental and internal_only are deliberately excluded because the checklist tags them as not-promised.

What looks good

• The meta-test approach (parse the rst, cross-reference SUPPORTED_FEATURES) is the right shape -- a missing test file or a new public tier without a row both surface as a hard test failure, not a doc-only drift.
• The Placeholder PR cross-references section gives the rockout final summary a concrete list of links to swap in once sub-PRs 1-4 land.
• The xfail on the uppercase SSRF case is honest -- it documents the dependency on sub-PR 5 in the test's reason string rather than hiding the gap.
• The .. seealso:: link from geotiff.rst keeps the audit checklist discoverable from the main GeoTIFF reference page.

Checklist

• Algorithm matches reference/paper -- N/A (docs/tests only)
• All implemented backends produce consistent results -- N/A
• NaN handling is correct -- N/A
• Edge cases covered by tests -- meta-test covers the realistic drift modes
• Dask chunk boundaries handled correctly -- N/A
• No premature materialization -- N/A
• Benchmark exists or is not needed -- not needed
• README feature matrix updated -- not needed (per rockout brief)
• Docstrings present and accurate -- the test module's docstring documents what each gate pins

[brendancol]

PR Review (follow-up): GeoTIFF release gate / audit checklist

Second pass after the review fixes in commit 6bafc72.

Disposition of original findings

Suggestions:

1. (fixed) xrspatial/geotiff/tests/test_release_gate_2321.py:153 -- raises= is now (ValueError, UnsafeURLError). A regression that raises some other exception class will fail loudly instead of silently xfailing.
2. (fixed) docs/source/reference/release_gate_geotiff.rst:268 -- the HTTP SSRF defense row now cites test_ssrf_hardening_1664.py and test_dns_rebinding_pin_issue_1846.py alongside the meta-gate.
3. (fixed) xrspatial/geotiff/tests/test_release_gate_2321.py:62 -- gate 1 now also asserts every cited path's leaf name starts with test_.

Nits:

1. (dismissed) Mixed underline length in the rst: cosmetic only, the existing reference pages use the same loose style, and forcing a uniform width would just churn the diff.
2. (dismissed) Toctree placement after geotiff_internals: matches the surrounding flat ordering and the review already noted the current placement is fine.
3. (fixed) _PROMISED_TIERS now carries a comment explaining why experimental and internal_only are excluded.

Re-check

pytest xrspatial/geotiff/tests/test_release_gate_2321.py -- 4 passed, 1 xfailed (uppercase SSRF, pending #2326).

No new findings. Approving in spirit, but per rockout rules this stays a COMMENTED review rather than an APPROVED one.