Reason or Problem
The GeoTIFF module exposes a long list of capabilities (codecs, readers, writers, COG, BigTIFF, VRT, sidecars, GPU paths, permissive opt-ins). The SUPPORTED_FEATURES dict in xrspatial/geotiff/_attrs.py already tags each feature with a tier (stable / advanced / experimental / internal_only), but the user-facing meaning of those tier strings is not written down anywhere a user can find from the docs index.
The release-gate page (reference/release_gate_geotiff.rst) is an internal audit checklist. The main reference/geotiff.rst page covers the stable COG contract but does not define every tier in one place. A reader cannot answer "what does advanced actually promise me?" from a single page.
This is PR 2 of 6 under epic #2340.
Proposal
Add a release-contract page at docs/source/reference/geotiff_release_contract.md that:
- Defines each tier in one short paragraph (stable, advanced, experimental, internal-only, unsupported) in user-facing terms: "can I rely on this in production", "what changes without warning", and so on.
- Has a single feature-tier table covering every entry in
SUPPORTED_FEATURES, grouped by codec / reader / writer, plus the unsupported combinations called out in the epic (full GDAL VRT parity, warped VRTs, rotated/sheared write, silent mixed-metadata flattening).
- Is linked from
docs/source/reference/geotiff.rst so it shows up in the toctree.
Design:
- Markdown for the new page so the table is easy to scan and edit. Match the format used by other reference pages.
- Tier wording mirrors the
SUPPORTED_FEATURES block comments and the existing release-gate notes, so the runtime constant and the docs stay in lockstep.
- The unsupported tier is a doc-only concept. It does not appear in
SUPPORTED_FEATURES; it covers combinations that explicitly fail or are out of contract for the release.
Usage:
A reader navigating the GeoTIFF docs sees a top-level link to the release contract and can read what each tier means before picking a feature. Release notes can be drafted from the table directly.
Value:
Closes the docs side of epic #2340: the release has a written GeoTIFF support contract that is unambiguous and discoverable. No code changes; no risk to existing behaviour.
Stakeholders and Impacts
Touches docs/source/reference/ only. No changes to _attrs.py, public API docstrings, opt-in enforcement, or tests. Those are parallel PRs under epic #2340.
Drawbacks
A docs-only page can drift from SUPPORTED_FEATURES if reviewers forget to update both. The tier wording is kept short and cross-linked to the runtime constant to make drift obvious.
Alternatives
- Inline the contract into the existing
geotiff.rst page. The existing page is already long, and the release-contract concept deserves its own anchor for release-note links.
- Put the tier definitions in
_attrs.py docstrings only. End users do not read source-level docstrings.
Additional Notes or Context
Parent epic: #2340 (GeoTIFF release contract and feature tiering). PR 2 of 6.
Reason or Problem
The GeoTIFF module exposes a long list of capabilities (codecs, readers, writers, COG, BigTIFF, VRT, sidecars, GPU paths, permissive opt-ins). The
SUPPORTED_FEATURESdict inxrspatial/geotiff/_attrs.pyalready tags each feature with a tier (stable/advanced/experimental/internal_only), but the user-facing meaning of those tier strings is not written down anywhere a user can find from the docs index.The release-gate page (
reference/release_gate_geotiff.rst) is an internal audit checklist. The mainreference/geotiff.rstpage covers the stable COG contract but does not define every tier in one place. A reader cannot answer "what doesadvancedactually promise me?" from a single page.This is PR 2 of 6 under epic #2340.
Proposal
Add a release-contract page at
docs/source/reference/geotiff_release_contract.mdthat:SUPPORTED_FEATURES, grouped by codec / reader / writer, plus the unsupported combinations called out in the epic (full GDAL VRT parity, warped VRTs, rotated/sheared write, silent mixed-metadata flattening).docs/source/reference/geotiff.rstso it shows up in the toctree.Design:
SUPPORTED_FEATURESblock comments and the existing release-gate notes, so the runtime constant and the docs stay in lockstep.SUPPORTED_FEATURES; it covers combinations that explicitly fail or are out of contract for the release.Usage:
A reader navigating the GeoTIFF docs sees a top-level link to the release contract and can read what each tier means before picking a feature. Release notes can be drafted from the table directly.
Value:
Closes the docs side of epic #2340: the release has a written GeoTIFF support contract that is unambiguous and discoverable. No code changes; no risk to existing behaviour.
Stakeholders and Impacts
Touches
docs/source/reference/only. No changes to_attrs.py, public API docstrings, opt-in enforcement, or tests. Those are parallel PRs under epic #2340.Drawbacks
A docs-only page can drift from
SUPPORTED_FEATURESif reviewers forget to update both. The tier wording is kept short and cross-linked to the runtime constant to make drift obvious.Alternatives
geotiff.rstpage. The existing page is already long, and the release-contract concept deserves its own anchor for release-note links._attrs.pydocstrings only. End users do not read source-level docstrings.Additional Notes or Context
Parent epic: #2340 (GeoTIFF release contract and feature tiering). PR 2 of 6.