Skip to content

Docs: GeoTIFF release-contract page defining tier semantics #2347

@brendancol

Description

@brendancol

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:

  1. 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.
  2. 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).
  3. 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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationgeotiffGeoTIFF module

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions