Skip to content

Commit

Permalink
docs: document support policies (#1640)
Browse files Browse the repository at this point in the history
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
  • Loading branch information
rickeylev authored Dec 21, 2023
1 parent 8f1ac0a commit 83e9255
Show file tree
Hide file tree
Showing 3 changed files with 67 additions and 1 deletion.
6 changes: 5 additions & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
1 change: 1 addition & 0 deletions docs/sphinx/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,6 +61,7 @@ pip
coverage
gazelle
Contributing <contributing>
support
Changelog <changelog>
api/index
glossary
Expand Down
61 changes: 61 additions & 0 deletions docs/sphinx/support.md
Original file line number Diff line number Diff line change
@@ -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 <project:#contributing>
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.

0 comments on commit 83e9255

Please sign in to comment.