# [DRAFT] Compiler backport processes/policies

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