Skip to content

Add GeoTIFF release-contract docs page#2351

Merged
brendancol merged 2 commits into
mainfrom
issue-2347
May 24, 2026
Merged

Add GeoTIFF release-contract docs page#2351
brendancol merged 2 commits into
mainfrom
issue-2347

Conversation

@brendancol
Copy link
Copy Markdown
Contributor

Summary

Adds the user-facing GeoTIFF release contract page (epic #2340, PR 2 of 6):

  • New page docs/source/reference/geotiff_release_contract.md defines every tier (stable, advanced, experimental, internal-only, unsupported) in one short paragraph each, then lists every entry in xrspatial.geotiff.SUPPORTED_FEATURES (codecs, readers, writers) against its tier in a single table.
  • Links the new page from the existing geotiff.rst seealso block and adds it to the reference toctree in index.rst.
  • The unsupported tier is doc-only (not in SUPPORTED_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

  • Sphinx build renders the new page (markdown via myst-parser, already enabled for geotiff_internals.md).
  • The new page appears under Reference in the rendered toctree.
  • The seealso block on reference/geotiff.rst resolves to the new page.
  • Every entry in xrspatial.geotiff.SUPPORTED_FEATURES shows up in exactly one row of the tier table.

Closes #2347.

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.
@github-actions github-actions Bot added the performance PR touches performance-sensitive code label May 24, 2026
Copy link
Copy Markdown
Contributor Author

@brendancol brendancol left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 in docs/source/reference/ uses dotted names (reference.geotiff, reference.geotiff_release_gate). Switching to reference.geotiff_release_contract keeps the naming consistent across the directory. Update the :ref: in geotiff.rst to 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_FEATURES appears 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:523 and _writers/gpu.py:410 ("cog=True is not supported for file-like destinations").
  • The :ref: target on the new MyST page is reachable from geotiff.rst via the standard MyST (slug)= mechanism; the seealso block edit and toctree edit look correct.
  • The closing "Keeping this page honest" paragraph names the right cross-reference (_attrs.py plus the release-gate page) and matches how the existing release-gate page describes its role.

Checklist

  • Tier strings match SUPPORTED_FEATURES at 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.
Copy link
Copy Markdown
Contributor Author

@brendancol brendancol left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Follow-up review pass

After commit 7e4f46d8:

Suggestions

  • Anchor naming -- fixed. Anchor is now (reference.geotiff_release_contract)= and the :ref: in geotiff.rst matches.

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:523 and _writers/gpu.py:410 confirmed as the sources of the quoted error string.
  • No new findings on the re-read; ready to merge from a review perspective.

@brendancol brendancol merged commit c4878d6 into main May 24, 2026
7 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

performance PR touches performance-sensitive code

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Docs: GeoTIFF release-contract page defining tier semantics

1 participant