Skip to content

Commit a53579c

Browse files
flip1995flip1995
committed
Update backport, release and sync documentation
1 parent 8698c31 commit a53579c

File tree

3 files changed

+158
-133
lines changed

3 files changed

+158
-133
lines changed

‎book/src/development/infrastructure/backport.md

Lines changed: 82 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -5,68 +5,107 @@ Backports in Clippy are rare and should be approved by the Clippy team. For
55
example, a backport is done, if a crucial ICE was fixed or a lint is broken to a
66
point, that it has to be disabled, before landing on stable.
77

8-
Backports are done to the `beta` branch of Clippy. Backports to stable Clippy
9-
releases basically don't exist, since this would require a Rust point release,
10-
which is almost never justifiable for a Clippy fix.
8+
> Note: If you think a PR should be backported you can label it with
9+
> `beta-nominated`. This has to be done before the Thursday the week before the
10+
> release.
1111
12+
## Filtering PRs to backport
1213

13-
## Backport the changes
14+
First, find all labeled PRs using [this filter][beta-accepted-prs].
15+
16+
Next, look at each PR individually. There are a few things to check. Those need
17+
some explanation and are quite subjective. Good judgement is required.
18+
19+
1. **Is the fix worth a backport?**
20+
21+
This is really subjective. An ICE fix usually is. Moving a lint to a _lower_
22+
group usually as well. An FP fix usually not (on its own). If a backport is
23+
done anyway, FP fixes might also be included. If the PR has a lot of changes,
24+
backports must be considered more carefully.
25+
26+
2. **Is the problem that was fixed by the PR already in `beta`?**
27+
28+
It could be that the problem that was fixed by the PR hasn't made it to the
29+
`beta` branch of the Rust repo yet. If that's the case, and the fix is
30+
already synced to the Rust repo, the fix doesn't need to be backported. If
31+
the fix PR is not synced yet, the fix PR either needs to be "backported" to
32+
the Rust `master` branch or to `beta` in the next backport cycle.
33+
34+
3. **Is the fix already synced to `master`?**
35+
36+
The fix must already be synced to the Rust `master` branch. Otherwise, the
37+
next `beta` will be missing this fix again. If it is not yet in `master` it
38+
should probably not be backported. If the backport is really important, do an
39+
out-of-cycle sync first. However, the out-of-cycle sync should be small,
40+
because the changes in that sync will get right into `beta`, without being
41+
tested in `nightly` first.
42+
43+
[beta-accepted-prs]: https://github.com/rust-lang/rust-clippy/issues?q=label%3Abeta-nominated
44+
45+
## Preparation
46+
47+
> Note: All commands in this chapter will be run in the Rust clone.
48+
49+
Follow the instructions in [defining remotes] to define the `clippy-upstream`
50+
remote in the Rust repository.
1451

15-
Backports are done on the beta branch of the Clippy repository.
52+
After that, fetch the remote with
1653

1754
```bash
18-
# Assuming the current directory corresponds to the Clippy repository
19-
$ git checkout beta
20-
$ git checkout -b backport
21-
$ git cherry-pick <SHA> # `<SHA>` is the commit hash of the commit(s), that should be backported
22-
$ git push origin backport
55+
git fetch clippy-upstream master
2356
```
2457

25-
Now you should test that the backport passes all the tests in the Rust
26-
repository. You can do this with:
58+
Then, switch to the `beta` branch:
2759

2860
```bash
29-
# Assuming the current directory corresponds to the Rust repository
30-
$ git checkout beta
31-
# Make sure to change `your-github-name` to your github name in the following command
32-
$ git subtree pull -p src/tools/clippy https://github.com/<your-github-name>/rust-clippy backport
33-
$ ./x.py test src/tools/clippy
61+
git switch beta
62+
git fetch upstream
63+
git reset --hard upstream/beta
3464
```
3565

36-
Should the test fail, you can fix Clippy directly in the Rust repository. This
37-
has to be first applied to the Clippy beta branch and then again synced to the
38-
Rust repository, though. The easiest way to do this is:
66+
[defining remotes]: release.md#defining-remotes
67+
68+
## Backport the changes
69+
70+
When PR is merged with the GitHub merge queue, the PR is closed with the message
71+
72+
> <PR title> (#<PR number>)
73+
74+
This commit needs to be backported. To do that, find the `<sha1>` of that commit
75+
and run the following command in the clone of the **Rust repository**:
3976

4077
```bash
41-
# In the Rust repository
42-
$ git diff --patch --relative=src/tools/clippy > clippy.patch
43-
# In the Clippy repository
44-
$ git apply /path/to/clippy.patch
45-
$ git add -u
46-
$ git commit -m "Fix rustup fallout"
47-
$ git push origin backport
78+
git cherry-pick -m 1 `<sha1>`
4879
```
4980

50-
After this, you can open a PR to the `beta` branch of the Clippy repository.
81+
Do this for all PRs that should be backported.
5182

83+
## Open PR in the Rust repository
5284

53-
## Update Clippy in the Rust Repository
85+
Next, open the PR for the backport. Make sure, the PR is opened towards the
86+
`beta` branch and not the `master` branch. The PR description should look like
87+
this:
5488

55-
This step must be done, **after** the PR of the previous step was merged.
89+
```
90+
[beta] Clippy backports
5691
57-
After the backport landed in the Clippy repository, the branch has to be synced
58-
back to the beta branch of the Rust repository.
92+
r? @Mark-Simulacrum
5993
60-
```bash
61-
# Assuming the current directory corresponds to the Rust repository
62-
$ git checkout beta
63-
$ git checkout -b clippy_backport
64-
$ git subtree pull -p src/tools/clippy https://github.com/rust-lang/rust-clippy beta
65-
$ git push origin clippy_backport
94+
Backports:
95+
- <Link to the Clippy PR>
96+
- ...
97+
98+
<Short summary what is backported and why>
6699
```
67100

68-
Make sure to test the backport in the Rust repository before opening a PR. This
69-
is done with `./x.py test src/tools/clippy`. If that passes all tests, open a PR
70-
to the `beta` branch of the Rust repository. In this PR you should tag the
71-
Clippy team member, that agreed to the backport or the `@rust-lang/clippy` team.
72-
Make sure to add `[beta]` to the title of the PR.
101+
Mark is from the release team and they ultimately have to merge the PR before
102+
branching a new `beta` version. Tag them to take care of the backport. Next,
103+
list all the backports and give a short summary what's backported and why it is
104+
worth backporting this.
105+
106+
## Relabel backported PRs
107+
108+
When a PR is backported to Rust `beta`, label the PR with `beta-accepted`. This
109+
will then get picked up when [writing the changelog].
110+
111+
[writing the changelog]: changelog_update.md#31-include-beta-accepted-prs

‎book/src/development/infrastructure/release.md

Lines changed: 62 additions & 63 deletions
Original file line numberDiff line numberDiff line change
@@ -7,112 +7,111 @@ Clippy is released together with stable Rust releases. The dates for these
77
releases can be found at the [Rust Forge]. This document explains the necessary
88
steps to create a Clippy release.
99

10-
1. [Remerge the `beta` branch](#remerge-the-beta-branch)
11-
2. [Update the `beta` branch](#update-the-beta-branch)
12-
3. [Find the Clippy commit](#find-the-clippy-commit)
13-
4. [Tag the stable commit](#tag-the-stable-commit)
14-
5. [Update `CHANGELOG.md`](#update-changelogmd)
15-
16-
> _NOTE:_ This document is for stable Rust releases, not for point releases. For
17-
> point releases, step 1. and 2. should be enough.
10+
1. [Defining Remotes](#defining-remotes)
11+
1. [Bump Version](#bump-version)
12+
1. [Find the Clippy commit](#find-the-clippy-commit)
13+
1. [Update the `beta` branch](#update-the-beta-branch)
14+
1. [Update the `stable` branch](#update-the-stable-branch)
15+
1. [Tag the stable commit](#tag-the-stable-commit)
16+
1. [Update `CHANGELOG.md`](#update-changelogmd)
1817

1918
[Rust Forge]: https://forge.rust-lang.org/
2019

21-
## Remerge the `beta` branch
20+
## Defining Remotes
21+
22+
You may want to define the `upstream` remote of the Clippy project to simplify
23+
the following steps. However, this is optional and you can replace `upstream`
24+
with the full URL instead.
2225

23-
This step is only necessary, if since the last release something was backported
24-
to the beta Rust release. The remerge is then necessary, to make sure that the
25-
Clippy commit, that was used by the now stable Rust release, persists in the
26-
tree of the Clippy repository.
26+
```bash
27+
git remote add upstream [email protected]:rust-lang/rust-clippy
28+
```
2729

28-
To find out if this step is necessary run
30+
## Bump Version
31+
32+
When a release needs to be done, `cargo test` will fail, if the versions in the
33+
`Cargo.toml` are not correct. During that sync, the versions need to be bumped.
34+
This is done by running:
2935

3036
```bash
31-
# Assumes that the local master branch of rust-lang/rust-clippy is up-to-date
32-
$ git fetch upstream
33-
$ git branch master --contains upstream/beta
37+
cargo dev release bump_version
3438
```
3539

36-
If this command outputs `master`, this step is **not** necessary.
40+
This will increase the version number of each relevant `Cargo.toml` file. After
41+
that, just commit the updated files with:
3742

3843
```bash
39-
# Assuming `HEAD` is the current `master` branch of rust-lang/rust-clippy
40-
$ git checkout -b backport_remerge
41-
$ git merge upstream/beta
42-
$ git diff # This diff has to be empty, otherwise something with the remerge failed
43-
$ git push origin backport_remerge # This can be pushed to your fork
44+
git commit -m "Bump Clippy version -> 0.1.XY" **/*Cargo.toml
4445
```
4546

46-
After this, open a PR to the master branch. In this PR, the commit hash of the
47-
`HEAD` of the `beta` branch must exist. In addition to that, no files should be
48-
changed by this PR.
47+
`XY` should be exchanged with the corresponding version
4948

50-
## Update the `beta` branch
49+
## Find the Clippy commit
5150

52-
This step must be done **after** the PR of the previous step was merged.
51+
For both, updating the `beta` and the `stable` branch, the first step is to find
52+
the Clippy commit of the last Clippy sync done in the respective Rust branch.
5353

54-
First, the Clippy commit of the `beta` branch of the Rust repository has to be
55-
determined.
54+
Running the following commands _in the Rust repo_ will get the commit for the
55+
specified `<branch>`:
5656

5757
```bash
58-
# Assuming the current directory corresponds to the Rust repository
59-
$ git fetch upstream
60-
$ git checkout upstream/beta
61-
$ BETA_SHA=$(git log --oneline -- src/tools/clippy/ | grep -o "Merge commit '[a-f0-9]*' into .*" | head -1 | sed -e "s/Merge commit '\([a-f0-9]*\)' into .*/\1/g")
58+
git switch <branch>
59+
SHA=$(git log --oneline -- src/tools/clippy/ | grep -o "Merge commit '[a-f0-9]*' into .*" | head -1 | sed -e "s/Merge commit '\([a-f0-9]*\)' into .*/\1/g")
6260
```
6361

64-
After finding the Clippy commit, the `beta` branch in the Clippy repository can
65-
be updated.
62+
Where `<branch>` is one of `stable`, `beta`, or `master`.
63+
64+
## Update the `beta` branch
65+
66+
After getting the commit of the `beta` branch, the `beta` branch in the Clippy
67+
repository can be updated.
6668

6769
```bash
68-
# Assuming the current directory corresponds to the Clippy repository
69-
$ git checkout beta
70-
$ git reset --hard $BETA_SHA
71-
$ git push upstream beta
70+
git checkout beta
71+
git reset --hard $SHA
72+
git push upstream beta
7273
```
7374

74-
## Find the Clippy commit
75+
## Update the `stable` branch
7576

76-
The first step is to tag the Clippy commit, that is included in the stable Rust
77-
release. This commit can be found in the Rust repository.
77+
After getting the commit of the `stable` branch, the `stable` branch in the
78+
Clippy repository can be updated.
7879

7980
```bash
80-
# Assuming the current directory corresponds to the Rust repository
81-
$ git fetch upstream # `upstream` is the `rust-lang/rust` remote
82-
$ git checkout 1.XX.0 # XX should be exchanged with the corresponding version
83-
$ SHA=$(git log --oneline -- src/tools/clippy/ | grep -o "Merge commit '[a-f0-9]*' into .*" | head -1 | sed -e "s/Merge commit '\([a-f0-9]*\)' into .*/\1/g")
81+
git checkout stable
82+
git reset --hard $SHA
83+
git push upstream stable
8484
```
8585

86-
## Tag the stable commit
86+
## Tag the `stable` commit
87+
88+
After updating the `stable` branch, tag the HEAD commit and push it to the
89+
Clippy repo.
8790

88-
After finding the Clippy commit, it can be tagged with the release number.
91+
> Note: Only push the tag, once the Deploy GitHub action of the `beta` branch is
92+
> finished. Otherwise the deploy for the tag might fail.
8993
9094
```bash
91-
# Assuming the current directory corresponds to the Clippy repository
92-
$ git checkout $SHA
93-
$ git tag rust-1.XX.0 # XX should be exchanged with the corresponding version
94-
$ git push upstream rust-1.XX.0 # `upstream` is the `rust-lang/rust-clippy` remote
95+
git tag rust-1.XX.0 # XX should be exchanged with the corresponding version
96+
git push upstream rust-1.XX.0 # `upstream` is the `rust-lang/rust-clippy` remote
9597
```
9698

9799
After this, the release should be available on the Clippy [release page].
98100

99101
[release page]: https://github.com/rust-lang/rust-clippy/releases
100102

101-
## Update the `stable` branch
103+
## Publish `clippy_utils`
102104

103-
At this step you should have already checked out the commit of the `rust-1.XX.0`
104-
tag. Updating the stable branch from here is as easy as:
105+
The `clippy_utils` crate is published to `crates.io` without any stability
106+
guarantees. To do this, after the [sync] and the release is done, switch back to
107+
the `upstream/master` branch and publish `clippy_utils`:
105108

106109
```bash
107-
# Assuming the current directory corresponds to the Clippy repository and the
108-
# commit of the just created rust-1.XX.0 tag is checked out.
109-
$ git push upstream rust-1.XX.0:stable # `upstream` is the `rust-lang/rust-clippy` remote
110+
git switch master && git pull upstream master
111+
cargo publish --manifest-path clippy_utils/Cargo.toml
110112
```
111113

112-
> _NOTE:_ Usually there are no stable backports for Clippy, so this update
113-
> should be possible without force pushing or anything like this. If there
114-
> should have happened a stable backport, make sure to re-merge those changes
115-
> just as with the `beta` branch.
114+
[sync]: sync.md
116115

117116
## Update `CHANGELOG.md`
118117

0 commit comments

Comments
 (0)