Add GeoTIFF release-contract docs page#2351
Merged
Merged
Conversation
Adds docs/source/reference/geotiff_release_contract.md with the user-facing meaning of every support tier (stable, advanced, experimental, internal-only, unsupported) and a feature-tier table covering every entry in SUPPORTED_FEATURES (codecs, readers, writers) plus the unsupported combinations from epic #2340. Links the new page from the seealso block in geotiff.rst and adds it to the reference toctree in index.rst. Docs-only. No changes to _attrs.py, public API docstrings, opt-in enforcement, or tests; those are parallel PRs under epic #2340.
brendancol
commented
May 24, 2026
Contributor
Author
brendancol
left a comment
There was a problem hiding this comment.
PR Review: Add GeoTIFF release-contract docs page
Blockers (must fix before merge)
None.
Suggestions (should fix, not blocking)
docs/source/reference/geotiff_release_contract.md:1-- the anchor uses hyphens (reference-geotiff-release-contract) but every other reference target indocs/source/reference/uses dotted names (reference.geotiff,reference.geotiff_release_gate). Switching toreference.geotiff_release_contractkeeps the naming consistent across the directory. Update the:ref:ingeotiff.rstto match. Sphinx accepts both, so this is style, not correctness.
Nits (optional improvements)
docs/source/reference/geotiff_release_contract.md-- the "Unsupported for this release" intro says combinations "either fail with an actionable error or are documented as not supported." The warped/reprojection VRT bullet lands in the second bucket: the VRT reader does not interpret warp tags rather than raising. One extra line per bullet (or a parenthetical) calling out which items are "fails loudly" vs "silently ignored" would match the epic's "fail loudly instead of partially working" principle.
What looks good
- Every entry in
xrspatial.geotiff.SUPPORTED_FEATURESappears in exactly one row of the tier table, and the tier strings match the runtime values exactly. - Opt-in flag names (
allow_experimental_codecs=True,allow_internal_only_jpeg=True) match the public API surface in_writer.py. - The "File-like destinations with
cog=True" unsupported bullet matches the enforcement in_writers/eager.py:523and_writers/gpu.py:410("cog=True is not supported for file-like destinations"). - The
:ref:target on the new MyST page is reachable fromgeotiff.rstvia the standard MyST(slug)=mechanism; theseealsoblock edit and toctree edit look correct. - The closing "Keeping this page honest" paragraph names the right cross-reference (
_attrs.pyplus the release-gate page) and matches how the existing release-gate page describes its role.
Checklist
- Tier strings match
SUPPORTED_FEATURESat runtime (codec/reader/writer counts: 10/10/8, matches the dict). - Opt-in flag names match the public API.
- Unsupported list matches the epic #2340 proposal.
- Toctree entry placed next to other geotiff pages.
- No code changes, no test changes; scope respected.
- [n/a] Algorithm match, NaN handling, dask chunk boundaries, materialization, benchmarks, README feature matrix -- docs-only PR.
…2347) - Rename the MyST anchor from `reference-geotiff-release-contract` to `reference.geotiff_release_contract` so it matches the dotted naming used by every other reference target in `docs/source/reference/` (e.g. `reference.geotiff`, `reference.geotiff_release_gate`). Update the `:ref:` in `geotiff.rst` accordingly. - Tag each bullet in the "Unsupported for this release" section as either **(fails loudly)** or **(documented-only)** so the fail-loudly-not-partial-work principle from epic #2340 is visible at the bullet level. Quote the literal error string raised by the COG writer for file-like destinations. Disposition of the original review: - Suggestion (anchor naming): fixed. - Nit (per-bullet fail-mode): fixed. - Blockers: none reported.
brendancol
commented
May 24, 2026
Contributor
Author
brendancol
left a comment
There was a problem hiding this comment.
Follow-up review pass
After commit 7e4f46d8:
Suggestions
- Anchor naming -- fixed. Anchor is now
(reference.geotiff_release_contract)=and the:ref:ingeotiff.rstmatches.
Nits
- Per-bullet fail-mode tags -- fixed. Each item in "Unsupported for this release" now carries either (fails loudly) or (documented-only). The file-like-COG bullet also quotes the literal error message the writers raise.
Verification
- Markdown still parses cleanly via
myst_parser.docutils_. _writers/eager.py:523and_writers/gpu.py:410confirmed as the sources of the quoted error string.- No new findings on the re-read; ready to merge from a review perspective.
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
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
Adds the user-facing GeoTIFF release contract page (epic #2340, PR 2 of 6):
docs/source/reference/geotiff_release_contract.mddefines every tier (stable,advanced,experimental,internal-only,unsupported) in one short paragraph each, then lists every entry inxrspatial.geotiff.SUPPORTED_FEATURES(codecs, readers, writers) against its tier in a single table.geotiff.rstseealsoblock and adds it to the reference toctree inindex.rst.unsupportedtier is doc-only (not inSUPPORTED_FEATURES) and covers combinations the epic excludes: full GDAL VRT parity, warped VRTs, rotated/sheared GeoTIFF write, silent mixed-metadata flattening, file-like COG destinations.Out of scope
Per the epic, this PR is docs-only. No changes to
_attrs.py, public API docstrings, opt-in enforcement, or tests. Those are parallel PRs (PRs 1, 3, 4, 5, 6 of the epic).Backend coverage
Not applicable. Docs only.
Test plan
geotiff_internals.md).seealsoblock onreference/geotiff.rstresolves to the new page.xrspatial.geotiff.SUPPORTED_FEATURESshows up in exactly one row of the tier table.Closes #2347.