1# `rules_rust` backwards compatibility policy 2 3This document defines the backwards compatibility policy for rules_rust and 4defines the process for making compatibility breaking changes. Any exception to 5this process will have to be thoroughly discussed and there will have to be a 6consensus between maintainers that the exception should be granted. 7 8## What is a compatibility breaking change? 9 10A backwards compatible change has the property that a build that is green, 11correct, is using stable APIs of `rules_rust`, and is using a supported version 12of Bazel before the change is still green and correct after the change. In 13practice it means that users should not have to modify their project source 14files, their `BUILD` files, their `bzl` files, their `rust_toolchain` 15definitions, their platform definitions, or their build settings. 16 17A backwards compatible release has the property that it only contains backward 18compatible changes. 19 20`rules_rust` follow [SemVer 2.0.0](https://semver.org/). `rules_rust` promise 21that all minor version number and patch version number releases only contain 22backwards compatible changes. 23 24`rules_rust` don't make any guarantees about compatibility between a released 25version and the state of the `rules_rust` at HEAD. 26 27Backwards incompatible changes will have to follow a process in order to be 28released. Users will be given at least one release where the old behavior is 29still present but deprecated to allow smooth migration of their project to the 30new behavior. 31 32### Compatibility before 1.0 33 34All minor version number releases before version 1.0 can be backwards incompatible. 35Backwards incompatible changes still have to follow the the process, but minimum 36time for migration is reduced to 2 weeks. 37 38## What Bazel versions are supported? 39 40`rules_rust` support the current Bazel LTS at the time of a `rules_rust` 41release. 42 43Support for the current Bazel rolling release is on the best effort basis. If 44the CI build of `rules_rust` against the current Bazel rolling release is green, 45it has to stay green. If the build is already red (because the new Bazel rolling 46release had incompatible changes that broke `rules_rust`), it is acceptable to 47merge PRs leaving the build red as long as the reason for failure remains the 48same. We hope red CI with the current rolling release will be rare. 49 50`rules_rust` don't promise all new `rules_rust` features available to the 51current Bazel rolling release to be be available to the current Bazel LTS 52release (because Bazel compatibility policy doesn't allow us to make that 53promise, and some new features of `rules_rust` require new Bazel features that 54are only available in Bazel rolling releases). `rules_rust` will aim that new 55features available to the current Bazel rolling release will be available to the 56next Bazel LTS release at latest. 57 58Whenever there is a new Bazel LTS release, all releases of `rules_rust` will maintain 59support for the older LTS version for at least 3 months unless Bazel doesn't allow this. 60 61## What host platforms are supported? 62 63Platforms subject to backwards compatibility policy are 64`x86_64-unknown-linux-gnu` and `x86_64-apple-darwin` (platforms supported by `rules_rust`). 65Process for moving a best effort platform to a supported platform is consensus-based. 66 67## What are the stable APIs of `rules_rust`? 68 69`//rust:defs.bzl` is subject to the backwards compatibility policy. That means 70that anything directly accessible from this file is considered stable. 71 72`//rust/private/…` is not subject to the backwards compatibility policy. Content 73of this package is an implementation detail. 74 75`//cargo:defs.bzl` is subject to the backwards compatibility policy. 76 77`//cargo`, `//util`, `//tools`, `//test`, `//examples`, `//bindgen`, `//proto`, 78`//wasm_bindgen` and any packages not mentioned by this document are by default 79not subject to the backwards compatibility policy. 80 81Experimental build settings are not subject to the backward compatibility 82policy. They should be added to `//rust:experimental.bzl`. 83 84Incompatible build settings are subject to the backward compatibility policy, 85meaning the behavior of the flag cannot change in a backwards incompatible way. 86They should be added to `//rust:incompatible.bzl`. 87 88Bug fixes are not a breaking change by default. We'll use Common Sense (and we 89will pull in more maintainers and the community to discuss) if we see a certain 90bug fix is controversial. Incompatible changes to 91`//cargo:defs.bzl` that make `cargo_build_script` more accurately 92follow cargo's behaviour are considered bug fixes. 93 94## How to make a backwards incompatible change? 95 961. Create a GitHub issue (example: 97[Split rust_library into smaller rules#591](https://github.com/bazelbuild/rules_rust/issues/591)). 982. Describe the change, motivation for the change, provide migration 99instructions/tooling. 1003. Add a build setting into `//rust:incompatible.bzl` that removes the old 101behavior (whenever possible) or changes the current behavior (when just 102removing the old behavior is not possible). Ideally, users should not need to 103manually flip incompatible flags. 1044. Mention the link to the GitHub issue in error messages. Do not add a 105deprecation warning (warnings make the deprecation visible to every user 106building a project, not only to the maintainers of the project or the rules). 1075. Mention the issue in the `CHANGELOG` file. 1086. Give the community 3 months from the first release mentioning the issue until 109the flag flip to migrate. 110