Skip to content

Commit

Permalink
Update book for backport, release and sync
Browse files Browse the repository at this point in the history 
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.
  • Loading branch information
@flip1995
flip1995 committed May 17, 2024
1 parent 680256f commit 0dcb0ca
Show file tree
Hide file tree
Showing 3 changed files with 193 additions and 195 deletions.
125 changes: 82 additions & 43 deletions book/src/development/infrastructure/backport.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
118 changes: 51 additions & 67 deletions book/src/development/infrastructure/release.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
```
Expand All @@ -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].
Expand Down
Loading

0 comments on commit 0dcb0ca

Please sign in to comment.