From 83e925516abeb41cb9acdfc5f299d02e03a6f35c Mon Sep 17 00:00:00 2001 From: Richard Levasseur Date: Wed, 20 Dec 2023 22:46:22 -0800 Subject: [PATCH] docs: document support policies (#1640) This just writes down our support policies and puts them in a single location in the hosted docs. Summarized: * Bazel version support is as discussed from the maintainers meeting: upcoming, current, and last versions * Reference the Bazel rule compatibility guidelines (always having an incremental path to upgrade) * Described what experimental features mean. * Only support the latest rules_python version; older ones are best effort. * Only support platforms CI can run. Work towards #1361 --- CONTRIBUTING.md | 6 ++++- docs/sphinx/index.md | 1 + docs/sphinx/support.md | 61 ++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 67 insertions(+), 1 deletion(-) create mode 100644 docs/sphinx/support.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c6532d9ac..10d1149cc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -144,7 +144,11 @@ For the full details of types, see ## Generated files Some checked-in files are generated and need to be updated when a new PR is -merged. +merged: + +* **requirements lock files**: These are usually generated by a + `compile_pip_requirements` update target, which is usually in the same directory. + e.g. `bazel run //docs/sphinx:requirements.update` ## Core rules diff --git a/docs/sphinx/index.md b/docs/sphinx/index.md index bec652a0c..0a9c70f93 100644 --- a/docs/sphinx/index.md +++ b/docs/sphinx/index.md @@ -61,6 +61,7 @@ pip coverage gazelle Contributing +support Changelog api/index glossary diff --git a/docs/sphinx/support.md b/docs/sphinx/support.md new file mode 100644 index 000000000..a2b8e3ae2 --- /dev/null +++ b/docs/sphinx/support.md @@ -0,0 +1,61 @@ +# Support Policy + +The Bazel community maintains this repository. Neither Google nor the Bazel team +provides support for the code. However, this repository is part of the test +suite used to vet new Bazel releases. See the +page for information on our development workflow. + +## Supported rules_python Versions + +In general, only the latest version is supported. Backporting changes is +done on a best effort basis based on severity, risk of regressions, and +the willingness of volunteers. + +If you want or need particular functionality backported, then the best way +is to open a PR to demonstrate the feasibility of the backport. + +## Supported Bazel Versions + +The supported Bazel versions are: + +1. The latest rolling release +2. The active major release. +3. The major release prior to the active release. + +For (2) and (3) above, only the latest minor/patch version of the major release +is officially supported. Earlier minor/patch versions are supported on a +best-effort basis only. We increase the minimum minor/patch version as necessary +to fix bugs or introduce functionality relying on features introduced in later +minor/patch versions. + +See [Bazel's release support matrix](https://bazel.build/release#support-matrix) +for what versions are the rolling, active, and prior releases. + +## Supported Platforms + +We only support the platforms that our continuous integration jobs run, which +is Linux, Mac, and Windows. Code to support other platforms is allowed, but +can only be on a best-effort basis. + +## Compatibility Policy + +We generally follow the [Bazel Rule +Compatibility](https://bazel.build/release/rule-compatibility) guidelines, which +provides a path from an arbitrary release to the latest release in an +incremental fashion. + +Breaking changes are allowed, but follow a process to introduce them over +a series of releases to so users can still incrementally upgrade. See the +[Breaking Changes](contributing#breaking-changes) doc for the process. + +## Experimental Features + +An experimental features is functionality that may not be ready for general +use and may change quickly and/or significantly. Such features are denoted in +their name or API docs as "experimental". They may have breaking changes made at +any time. + +If you like or use an experimental feature, then file issues to request it be +taken out of experimental. Often times these features are experimental because +we need feedback or experience to verify they are working, useful, and worth the +effort of supporting.