diff --git a/docs/source/user_guide/index.rst b/docs/source/user_guide/index.rst index 07dfc56f6..eb6dac94d 100644 --- a/docs/source/user_guide/index.rst +++ b/docs/source/user_guide/index.rst @@ -8,6 +8,7 @@ User Guide :maxdepth: 1 caveats + stability_policy data_types classification fire diff --git a/docs/source/user_guide/stability_policy.rst b/docs/source/user_guide/stability_policy.rst new file mode 100644 index 000000000..b48f65431 --- /dev/null +++ b/docs/source/user_guide/stability_policy.rst @@ -0,0 +1,36 @@ +.. _user_guide.stability_policy: + +Stability policy and LTS commitment +=================================== + +This page states which parts of xarray-spatial are covered by long-term +support (LTS) in the 1.0.0 series, and what "stable" means here. + +What LTS covers +--------------- + +The high-level public spellings are the LTS surface: the names exported from +``xrspatial/__init__.py`` and the ``.xrs`` accessor on +``xarray.DataArray`` and ``xarray.Dataset``. Within the 1.0.x series these +names, their call signatures, and their documented return contracts do not +change in backward-incompatible ways. New optional keyword arguments may be +added; existing behavior for documented inputs is preserved. + +What "stable" requires +---------------------- + +Following the feature-tier work in #2415, a function reaching the ``stable`` +tier needs a documented contract and a release gate, not green cross-backend +tests alone. Concretely: + +- a documented input/output contract (dtypes, dims, attrs, nodata handling), +- no open CRITICAL or HIGH ``/deep-sweep`` findings in accuracy or security, +- a notebook example. + +Tiers below stable +------------------ + +``advanced`` and ``experimental`` functions work and are tested but carry +caveats or make no cross-backend parity claim. GPU and some Dask paths +usually stay at these tiers. The README feature matrix is the per-backend +source of truth for each function's tier.