Update book for backport, release and sync

flip1995 · flip1995 · commit 74aaeb71d348 · 2024-05-04T14:55:02.000+02:00
Those were outdated anyway. Now with switching to Josh, the documentation should
also be updated, as a lot of things got simplified. This updates the
documentation on how to do syncs with josh, how to do releases and how to do
backports.
diff --git a/book/src/development/infrastructure/backport.md b/book/src/development/infrastructure/backport.md
@@ -5,68 +5,107 @@ Backports in Clippy are rare and should be approved by the Clippy team. For
 example, a backport is done, if a crucial ICE was fixed or a lint is broken to a
 point, that it has to be disabled, before landing on stable.
 
-Backports are done to the `beta` branch of Clippy. Backports to stable Clippy
-releases basically don't exist, since this would require a Rust point release,
-which is almost never justifiable for a Clippy fix.
+> Note: If you think a PR should be backported you can label it with
+> `beta-nominated`. This has to be done before the Thursday the week before the
+> release.
 
+## Filtering PRs to backport
 
-## Backport the changes
+First, find all labeled PRs using [this filter][beta-accepted-prs].
+
+Next, look at each PR individually. There are a few things to check. Those need
+some explanation and are quite subjective. Good judgement is required.
+
+1. **Is the fix worth a backport?**
+
+   This is really subjective. An ICE fix usually is. Moving a lint to a _lower_
+   group usually as well. An FP fix usually not (on its own). If a backport is
+   done anyway, FP fixes might also be included. If the PR has a lot of changes,
+   backports must be considered more carefully.
+
+2. **Is the issue that was fixed by the PR in `beta` already?**
+
+   Maybe the issue being fixed didn't make it to `beta` in the Rust repo, yet.
+   If that's the case, and the fix is already synced to the Rust repo, the fix
+   doesn't need to be backported. If the fix PR is not synced yet, the fix PR
+   either needs to be "backported" to the Rust `master` branch or to `beta` in
+   the next backport cycle.
+
+3. **Is the fix already synced to `master`?**
+
+   The fix must already be synced to the Rust `master` branch. Otherwise, the
+   next `beta` will be missing this fix again. If it is not yet in `master` it
+   should probably not be backported. If the backport is really important, do an
+   out-of-cycle sync first. However, the out-of-cycle sync should be small,
+   because the changes in that sync will get right into `beta`, without being
+   tested in `nightly` first.
+
+[beta-accepted-prs]: https://github.com/rust-lang/rust-clippy/issues?q=label%3Abeta-nominated
+
+## Preparation
+
+> Note: All commands in this chapter will be run in the Rust clone.
+
+Follow the instructions in [defining remotes] to define the `clippy-upstream`
+remote in the Rust repository.
 
-Backports are done on the beta branch of the Clippy repository.
+After that, fetch the remote with
 
 ```bash
-# Assuming the current directory corresponds to the Clippy repository
-$ git checkout beta
-$ git checkout -b backport
-$ git cherry-pick <SHA>  # `<SHA>` is the commit hash of the commit(s), that should be backported
-$ git push origin backport
+$ git fetch clippy-upstream master
 ```
 
-Now you should test that the backport passes all the tests in the Rust
-repository. You can do this with:
+Then, switch to the `beta` branch:
 
 ```bash
-# Assuming the current directory corresponds to the Rust repository
-$ git checkout beta
-# Make sure to change `your-github-name` to your github name in the following command
-$ git subtree pull -p src/tools/clippy https://github.com/<your-github-name>/rust-clippy backport
-$ ./x.py test src/tools/clippy
+$ git switch beta
+$ git fetch upstream
+$ git reset --hard upstream/beta
 ```
 
-Should the test fail, you can fix Clippy directly in the Rust repository. This
-has to be first applied to the Clippy beta branch and then again synced to the
-Rust repository, though. The easiest way to do this is:
+[defining remotes]: release.md#defining-remotes
+
+## Backport the changes
+
+When `bors` merges a PR, the PR is closed with the message
+
+> `bors` merged commit `<sha1>` into `rust-lang:master`
+
+This `<sha1>` is the commit that needs to be backported. To do that, run the
+following command in the clone of the **Rust repository**:
 
 ```bash
-# In the Rust repository
-$ git diff --patch --relative=src/tools/clippy > clippy.patch
-# In the Clippy repository
-$ git apply /path/to/clippy.patch
-$ git add -u
-$ git commit -m "Fix rustup fallout"
-$ git push origin backport
+$ git cherry-pick -m 1 `<sha1>`
 ```
 
-After this, you can open a PR to the `beta` branch of the Clippy repository.
+Do this for all PRs that should be backported.
 
+## Open PR in the Rust repository
 
-## Update Clippy in the Rust Repository
+Next, open the PR for the backport. Make sure, the PR is opened towards the
+`beta` branch and not the `master` branch. The PR description should look like
+this:
 
-This step must be done, **after** the PR of the previous step was merged.
+```
+[beta] Clippy backports
 
-After the backport landed in the Clippy repository, the branch has to be synced
-back to the beta branch of the Rust repository.
+r? @Mark-Simulacrum
 
-```bash
-# Assuming the current directory corresponds to the Rust repository
-$ git checkout beta
-$ git checkout -b clippy_backport
-$ git subtree pull -p src/tools/clippy https://github.com/rust-lang/rust-clippy beta
-$ git push origin clippy_backport
+Backports:
+- <Link to the Clippy PR>
+- ...
+
+<Short summary what is backported and why>
 ```
 
-Make sure to test the backport in the Rust repository before opening a PR. This
-is done with `./x.py test src/tools/clippy`. If that passes all tests, open a PR
-to the `beta` branch of the Rust repository. In this PR you should tag the
-Clippy team member, that agreed to the backport or the `@rust-lang/clippy` team.
-Make sure to add `[beta]` to the title of the PR.
+Mark is from the release team and they ultimately have to merge the PR before
+branching a new `beta` version. Tag them to take care of the backport. Next,
+list all the backports and give a short summary what's backported and why it is
+worth backporting this.
+
+## Relabel backported PRs
+
+When a PR is backported to Rust `beta`, label the PR with `beta-accepted`. This
+will then get picked up when [writing the changelog].
+
+[writing the changelog]: changelog_update.md#31-include-beta-accepted-prs
diff --git a/book/src/development/infrastructure/release.md b/book/src/development/infrastructure/release.md
@@ -7,89 +7,89 @@ Clippy is released together with stable Rust releases. The dates for these
 releases can be found at the [Rust Forge]. This document explains the necessary
 steps to create a Clippy release.
 
-1. [Remerge the `beta` branch](#remerge-the-beta-branch)
-2. [Update the `beta` branch](#update-the-beta-branch)
-3. [Find the Clippy commit](#find-the-clippy-commit)
-4. [Tag the stable commit](#tag-the-stable-commit)
-5. [Update `CHANGELOG.md`](#update-changelogmd)
-
-> _NOTE:_ This document is for stable Rust releases, not for point releases. For
-> point releases, step 1. and 2. should be enough.
+1. [Defining Remotes](#defining-remotes)
+1. [Bump Version](#bump-version)
+1. [Find the Clippy commit](#find-the-clippy-commit)
+1. [Update the `beta` branch](#update-the-beta-branch)
+1. [Update the `stable` branch](#update-the-stable-branch)
+1. [Tag the stable commit](#tag-the-stable-commit)
+1. [Update `CHANGELOG.md`](#update-changelogmd)
 
 [Rust Forge]: https://forge.rust-lang.org/
 
-## Remerge the `beta` branch
-
-This step is only necessary, if since the last release something was backported
-to the beta Rust release. The remerge is then necessary, to make sure that the
-Clippy commit, that was used by the now stable Rust release, persists in the
-tree of the Clippy repository.
+## Defining Remotes
 
-To find out if this step is necessary run
+You may want to define the `upstream` remote of the Clippy project to simplify
+the following steps. However, this is optional and you can replace `upstream`
+with the full URL instead.
 
 ```bash
-# Assumes that the local master branch of rust-lang/rust-clippy is up-to-date
-$ git fetch upstream
-$ git branch master --contains upstream/beta
+$ git remote add upstream git@github.com:rust-lang/rust-clippy
 ```
 
-If this command outputs `master`, this step is **not** necessary.
+## Bump Version
 
-```bash
-# Assuming `HEAD` is the current `master` branch of rust-lang/rust-clippy
-$ git checkout -b backport_remerge
-$ git merge upstream/beta
-$ git diff  # This diff has to be empty, otherwise something with the remerge failed
-$ git push origin backport_remerge  # This can be pushed to your fork
+When a release needs to be done, `cargo test` will fail, if the versions in the
+`Cargo.toml` are not correct. During that sync, the versions need to be bumped.
+This is done by running:
+
+```
+$ cargo dev release bump_version
 ```
 
-After this, open a PR to the master branch. In this PR, the commit hash of the
-`HEAD` of the `beta` branch must exist. In addition to that, no files should be
-changed by this PR.
+This will increase the version number of each relevant `Cargo.toml` file. After
+that, just commit the updated files with:
 
-## Update the `beta` branch
+```bash
+# XX should be exchanged with the corresponding version
+$ git commit -m "Bump Clippy version -> 0.1.XX" **/*Cargo.toml
+```
+
+## Find the Clippy commit
 
-This step must be done **after** the PR of the previous step was merged.
+For both, updating the `beta` and the `stable` branch, the first step is to find
+the Clippy commit of the last Clippy sync done in the respective Rust branch.
 
-First, the Clippy commit of the `beta` branch of the Rust repository has to be
-determined.
+Running the following command will get the commit for the specified branch:
 
 ```bash
-# Assuming the current directory corresponds to the Rust repository
-$ git fetch upstream
-$ git checkout upstream/beta
-$ 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")
+$ SHA=$(cargo dev release commit /path/to/rust <branch>)
 ```
 
-After finding the Clippy commit, the `beta` branch in the Clippy repository can
-be updated.
+Where the `/path/to/rust` is a relative path to a Rust clone and the `<branch>`
+is one of `stable`, `beta`, or `master`.
+
+## Update the `beta` branch
+
+After getting the commit of the `beta` branch, the `beta` branch in the Clippy
+repository can be updated.
 
 ```bash
-# Assuming the current directory corresponds to the Clippy repository
 $ git checkout beta
-$ git reset --hard $BETA_SHA
+$ git reset --hard $SHA
 $ git push upstream beta
 ```
 
-## Find the Clippy commit
+## Update the `stable` branch
 
-The first step is to tag the Clippy commit, that is included in the stable Rust
-release. This commit can be found in the Rust repository.
+After getting the commit of the `stable` branch, the `stable` branch in the
+Clippy repository can be updated.
 
 ```bash
-# Assuming the current directory corresponds to the Rust repository
-$ git fetch upstream    # `upstream` is the `rust-lang/rust` remote
-$ git checkout 1.XX.0   # XX should be exchanged with the corresponding version
-$ 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")
+$ git checkout stable
+$ git reset --hard $SHA
+$ git push upstream stable
 ```
 
-## Tag the stable commit
+## Tag the `stable` commit
 
-After finding the Clippy commit, it can be tagged with the release number.
+After updating the `stable` branch, tag the HEAD commit and push it to the
+Clippy repo.
+
+> Note: Only push the tag, once the Deploy GitHub action of the `beta` branch is
+> finished. Otherwise the deploy for the tag might fail.
 
 ```bash
-# Assuming the current directory corresponds to the Clippy repository
-$ git checkout $SHA
 $ git tag rust-1.XX.0               # XX should be exchanged with the corresponding version
 $ git push upstream rust-1.XX.0     # `upstream` is the `rust-lang/rust-clippy` remote
 ```
@@ -98,22 +98,6 @@ After this, the release should be available on the Clippy [release page].
 
 [release page]: https://github.com/rust-lang/rust-clippy/releases
 
-## Update the `stable` branch
-
-At this step you should have already checked out the commit of the `rust-1.XX.0`
-tag. Updating the stable branch from here is as easy as:
-
-```bash
-# Assuming the current directory corresponds to the Clippy repository and the
-# commit of the just created rust-1.XX.0 tag is checked out.
-$ git push upstream rust-1.XX.0:stable  # `upstream` is the `rust-lang/rust-clippy` remote
-```
-
-> _NOTE:_ Usually there are no stable backports for Clippy, so this update
-> should be possible without force pushing or anything like this. If there
-> should have happened a stable backport, make sure to re-merge those changes
-> just as with the `beta` branch.
-
 ## Update `CHANGELOG.md`
 
 For this see the document on [how to update the changelog].
diff --git a/book/src/development/infrastructure/sync.md b/book/src/development/infrastructure/sync.md
