Skip to content

Commit af1f78a

Browse files
flip1995flip1995
authored
Update backport, release and sync documentation (#13700)
This updates the documentation after #13694. It is not based on that PR chain and can be merged independently, but should be merged after that PR. This is partly pulled from #12762, but removing the Josh parts. This includes instructions on how to publish `clippy_utils`. Closes #13556 (yes, this is the final PR 🙂) r? @blyxyas changelog: `clippy_utils` is now published to crates.io
2 parents ff4a26d + f5f2c51 commit af1f78a

File tree

3 files changed

+162
-133
lines changed

3 files changed

+162
-133
lines changed

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

+83-43
Original file line numberDiff line numberDiff line change
@@ -5,68 +5,108 @@ 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 (from warn- to allow-by-default) usually as well. An FP fix usually not
23+
(on its own). If a backport is done anyway, FP fixes might also be included.
24+
If the PR has a lot of changes, 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, as it
31+
will hit stable together with the commit that introduced the problem. If the
32+
fix PR is not synced yet, the fix PR either needs to be "backported" to the
33+
Rust `master` branch or to `beta` in the next backport cycle.
34+
35+
3. **Make sure that the fix is on `master` before porting to `beta`**
36+
37+
The fix must already be synced to the Rust `master` branch. Otherwise, the
38+
next `beta` will be missing this fix again. If it is not yet in `master` it
39+
should probably not be backported. If the backport is really important, do an
40+
out-of-cycle sync first. However, the out-of-cycle sync should be small,
41+
because the changes in that sync will get right into `beta`, without being
42+
tested in `nightly` first.
43+
44+
[beta-accepted-prs]: https://github.com/rust-lang/rust-clippy/issues?q=label%3Abeta-nominated
45+
46+
## Preparation
47+
48+
> Note: All commands in this chapter will be run in the Rust clone.
49+
50+
Follow the instructions in [defining remotes] to define the `clippy-upstream`
51+
remote in the Rust repository.
1452

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

1755
```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
56+
git fetch clippy-upstream master
2357
```
2458

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

2861
```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
62+
git switch beta
63+
git fetch upstream
64+
git reset --hard upstream/beta
3465
```
3566

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:
67+
[defining remotes]: release.md#defining-remotes
68+
69+
## Backport the changes
70+
71+
When a PR is merged with the GitHub merge queue, the PR is closed with the message
72+
73+
> \<PR title\> (#\<PR number\>)
74+
75+
This commit needs to be backported. To do that, find the `<sha1>` of that commit
76+
and run the following command in the clone of the **Rust repository**:
3977

4078
```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
79+
git cherry-pick -m 1 `<sha1>`
4880
```
4981

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

84+
## Open PR in the Rust repository
5285

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

55-
This step must be done, **after** the PR of the previous step was merged.
90+
```
91+
[beta] Clippy backports
5692
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.
93+
r? @Mark-Simulacrum
5994
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
95+
Backports:
96+
- <Link to the Clippy PR>
97+
- ...
98+
99+
<Short summary of what is backported and why>
66100
```
67101

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.
102+
Mark is from the release team and they ultimately have to merge the PR before
103+
branching a new `beta` version. Tag them to take care of the backport. Next,
104+
list all the backports and give a short summary what's backported and why it is
105+
worth backporting this.
106+
107+
## Relabel backported PRs
108+
109+
When a PR is backported to Rust `beta`, label the PR with `beta-accepted`. This
110+
will then get picked up when [writing the changelog].
111+
112+
[writing the changelog]: changelog_update.md#31-include-beta-accepted-prs

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

+65-63
Original file line numberDiff line numberDiff line change
@@ -7,112 +7,114 @@ 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.
25+
26+
```bash
27+
git remote add upstream [email protected]:rust-lang/rust-clippy
28+
```
2229

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.
30+
## Bump Version
2731

28-
To find out if this step is necessary run
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
8787

88-
After finding the Clippy commit, it can be tagged with the release number.
88+
After updating the `stable` branch, tag the HEAD commit and push it to the
89+
Clippy repo.
90+
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`
104+
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`:
102108

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:
109+
> Note: The Rustup PR bumping the nightly and Clippy version **must** be merged
110+
> before doing this.
105111
106112
```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
113+
git switch master && git pull upstream master
114+
cargo publish --manifest-path clippy_utils/Cargo.toml
110115
```
111116

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.
117+
[sync]: sync.md
116118

117119
## Update `CHANGELOG.md`
118120

0 commit comments

Comments
 (0)