diff --git a/docs/python-versions.md b/docs/python-versions.md index 902c0c0..bb81cff 100644 --- a/docs/python-versions.md +++ b/docs/python-versions.md @@ -10,7 +10,7 @@ fails if any workflow or template drifts from the supported set below. To change the supported versions, edit the two machine-readable markers here, update the table, then update each workflow to match and run the checker. - + ## Policy @@ -18,13 +18,25 @@ update the table, then update each workflow to match and run the checker. | Role | Versions | Notes | |------|----------|-------| | Primary | 3.12 | Default for single-version `python-version` inputs and the version quality checks run on | -| Supported matrix | 3.10, 3.11, 3.12, 3.13 | Comprehensive test matrix | +| Supported matrix | 3.10, 3.11, 3.12, 3.13, 3.14 | Comprehensive test matrix | | PR fast tier | 3.11, 3.12 | Subset for fast PR feedback; must be a subset of the supported matrix | -Pre-release versions (for example 3.14) are not part of the supported set until -they reach a stable release. Coverage and artifact handlers may reference a -pre-release version defensively (gated on the artifact existing) as long as no -test matrix or input default actively selects it. +A version joins the supported set once it has a stable release, and not before. +Do not name a specific version as the pre-release example here: the previous +wording used 3.14 as its illustration and quietly became wrong the moment 3.14 +shipped, which is how 3.14 stayed excluded for months after it qualified. State +the rule, let the marker above carry the facts. + +Coverage and artifact handlers may reference a not-yet-supported version +defensively (gated on the artifact existing) as long as no test matrix or input +default actively selects it. + +The supported set is a permit list, not a mandate. `check-python-versions.sh` +fails on a version *outside* the set, so adding a version only widens what +workflows may select; it does not add that version to any matrix or change any +default. Removing a version is the direction that carries risk, because it can +invalidate workflows and downstream `requires-python` floors that are already in +use. ## Enforcement