diff --git a/src/SUMMARY.md b/src/SUMMARY.md index d14d87dd..60305295 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -55,6 +55,7 @@ - [Review Policy](./compiler/reviews.md) - [Proposals, Approval and Stabilization](./compiler/proposals-and-stabilization.md) - [Adding ecosystem/integration test jobs/components to `rust-lang/rust` CI](./compiler/proposals-and-stabilization/ecosystem-integration-tests.md) + - [Backports](./compiler/backports.md) - [Third-party and Out-of-tree Crates Policy](./compiler/third-party-out-of-tree.md) - [Triage and Prioritization](./compiler/prioritization.md) - [Working Areas](./compiler/working-areas.md) diff --git a/src/compiler/README.md b/src/compiler/README.md index 4c5bdb65..a53ab6be 100644 --- a/src/compiler/README.md +++ b/src/compiler/README.md @@ -20,6 +20,9 @@ you're looking for the [rustc-dev-guide](https://rustc-dev-guide.rust-lang.org/) - *How do I make a contribution which is easy to review? How do I start reviewing as a team member?* - [Proposals, Approval and Stabilization](./proposals-and-stabilization.md) - *How do I propose a change to the compiler team? What approval is necessary for my change?* +- [Backports](./backports.md) + - *How do I request a beta and/or stable backport of a compiler change? How will compiler + backport nominations be handled?* - [Third-party and Out-of-tree Crates Policy](./third-party-out-of-tree.md) - *When can I add third-party crates to the compiler? When can I create a out-of-tree crate for the compiler?* diff --git a/src/compiler/backports.md b/src/compiler/backports.md new file mode 100644 index 00000000..9975613d --- /dev/null +++ b/src/compiler/backports.md @@ -0,0 +1,95 @@ +# Compiler change backports + +Sometimes compiler fixes need to be backported to the stable and/or beta channel to fix a +significant regression or to revert unintentional changes that weren't noticed when originally +merged. + +In case a backport is applied to the stable channel, the Rust project will release a patch release +(for example a 1.87.1 point release could follow the initial stable release 1.87.0). + +## Nominating for compiler backport review + +You can suggest evaluating a change to be backported by applying suitable labels to a GitHub pull +request: + +- Nominate for **beta** channel backport: [`beta-nominated`] +- Nominate for **stable** channel backport: [`stable-nominated`] + +or both, if the change should be considered to be backported to both release channels. Make sure the +pull request has a [`T-compiler`] label as well. + +In any case, you should **add a comment when you nominate the pull request for backport** providing +context for the compiler team backport reviewers about why it should be backported. + +**Backport nominations are not guaranteed be accepted**. + +Backports could be declined if compiler team determines that: + +- The **benefit** of backporting **does not sufficiently outweigh the risk of introducing *new* + regressions** to the beta/stable channels. +- The nominated change is **too complex** (which typically correlates with being too risky) to + backport. +- The nominated change is not merged in time for the stable or beta release channel (e.g. due to + implementation issues). +- (For beta backport nominations) The nominated change would be applied too close to the next stable + compiler release. Merging a backport at this time will mean very limited (if any) time for + testing. +- (For stable backport nominations) The nominated change does not sufficiently justify a patch + release on its own. Patch compiler releases usually happen when more backports pile up in the same + timespan. There is a *significantly higher bar* for stable backports and thus point releases, + because that *immediately* affects all stable channel users who update to the new point release. + In addition, not all stable regressions are equal: some are not very severe or are already there + since multiple releases. + +Beta regressions that slid to the stable channel will need a stable backport nomination (and a +subsequent patch release, if approved). + +The compiler team tries to make sure that critical issues (labeled with `P-critical`) do not +progress to the stable release. + +## Reviewing compiler backport nominations + +When one of [`beta-nominated`] or [`stable-nominated`] label is applied, a new thread is +automatically opened on Zulip in the [#t-compiler/backports] channel. Compiler team members can use +these Zulip threads to cast their vote asynchronously in favor of or raise concerns about +backporting. If you are a compiler team member and want to be notified of these threads, you should +subscribe that zulip channel. + +During the weekly triage meeting (happening on [#t-compiler/meetings], see [here](./meetings.md)), +the compiler team will finalize the decision and apply the relevant `{beta,stable}-accepted` label. + +### Should the backport of X be appoved? + +For compiler backport reviewers, here are some **non-exhaustive** considerations that they might +consider in making a backport decision: + +- Has the backport enough time to be tested? + - A stable point release will be *immediately* available to all users without any time to bake! +- How complex or risky is the nominated compiler change? Is the risk of the backport introducing new + regressions potentially worse than the regression or issue it addresses? +- How severe is the regression/issue being fixed? + - For example stable regressions are not all equal: some are not very severe or are already on + stable channel since multiple releases. + +At the end of the day, it's a risk vs benefit tradeoff decision. + +## How are approved backports handled? + +The [release team](../release/README.md) (`T-release`) will handle the backport at the end of the +current development cycle (see [release backporting](../release/backporting.md)). If a beta backport +nomination is approved too late, the release team may be unable to backport the change. + +Most of the time, accepted backports target the `master` branch. In rare circumstances, a beta +backport may need to *directly* target the `beta` branch. In this case, coordinate with the release +team before merging, by opening a new thread on the Zulip [#t-release +channel](https://rust-lang.zulipchat.com/#narrow/channel/241545-t-release)). + + +[`beta-nominated`]: https://github.com/rust-lang/rust/labels/beta-nominated +[`beta-accepted`]: https://github.com/rust-lang/rust/labels/beta-accepted +[`stable-nominated`]: https://github.com/rust-lang/rust/labels/stable-nominated +[`stable-accepted`]: https://github.com/rust-lang/rust/labels/stable-accepted +[#t-compiler/backports]: + https://rust-lang.zulipchat.com/#narrow/channel/474880-t-compiler.2Fbackports +[#t-compiler/meetings]: https://rust-lang.zulipchat.com/#narrow/channel/238009-t-compiler.2Fmeetings +[`T-compiler`]: https://github.com/rust-lang/rust/labels/T-compiler diff --git a/src/compiler/proposals-and-stabilization.md b/src/compiler/proposals-and-stabilization.md index 48359670..c0963858 100644 --- a/src/compiler/proposals-and-stabilization.md +++ b/src/compiler/proposals-and-stabilization.md @@ -334,6 +334,10 @@ circumstance. - **Approve using:** r+ (compiler leads) - Open a PR with the change affecting licensing and assign it to the team leads for review +### Stable/beta channel backport nominations of compiler changes + +See [*Compiler change backports*](./backports.md). + ### Adding ecosystem/integration test jobs/components to rust-lang/rust CI See [*Adding ecosystem/integration test jobs/components to rust-lang/rust CI*](./proposals-and-stabilization/custom-test-jobs.md).