Epic: GeoTIFF release contract and feature tiering

[brendancol]

Goal

Define the release promise for the GeoTIFF module so the next release is explicit about what is stable, advanced, experimental, internal-only, and unsupported.

This epic is the product boundary for the release. The goal is not to make every existing code path stable. The goal is to make the promised surface narrow, accurate, and defensible.

Release Principle

A user should be able to answer:

• Can I rely on this feature in production?
• What metadata is preserved?
• Which backends are covered by parity tests?
• Which options are advanced or experimental?
• Which inputs should fail loudly instead of partially working?

Proposed Tiering

Stable:

• Local GeoTIFF read/write.
• COG read/write for stable lossless codecs.
• CRS / transform / nodata attrs contract.
• Windowed reads where supported.
• Dask reads only where parity-tested against eager reads.

Advanced:

• Simple VRT mosaics.
• HTTP/fsspec reads.
• External .ovr sidecars.
• BigTIFF.
• Overview generation/selection.

Experimental:

• GPU read/write.
• LERC, JPEG2000/J2K, LZ4.
• Explicit CRS permissive escape hatches.
• Other paths without cross-backend numerical parity claims.

Internal-only:

• JPEG-in-TIFF path unless/until it is made externally interoperable with GDAL/libtiff/rasterio.

Unsupported for this release:

• Full GDAL VRT parity.
• Warped VRTs/reprojection VRTs unless separately implemented and tested.
• Rotated/sheared GeoTIFF write support.
• Silent mixed metadata flattening.

Work Items

• Audit SUPPORTED_FEATURES and align it with the release promise.
• Audit public docstrings for open_geotiff, read_geotiff_dask, read_geotiff_gpu, read_vrt, to_geotiff, write_geotiff_gpu, and write_vrt.
• Add a single feature-tier table in docs.
• Add a short release-contract page or section that explains the tier meanings.
• Ensure experimental/internal-only paths require explicit opt-ins where appropriate.
• Ensure unsupported combinations fail with actionable errors.

Acceptance Criteria

• The release has a written GeoTIFF support contract.
• Stable, advanced, experimental, internal-only, and unsupported features are unambiguous.
• No docs or docstrings imply full support for features outside the contract.
• Every stable feature has a corresponding release-gate test or is moved out of stable.
• Release notes can be written from this contract without caveats hidden in code comments.

Related Epics

• Correctness/parity release gate.
• Conservative VRT support contract.
• Remote/source safety hardening.
• Documentation and release readiness.