user0/rust
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Merge commit 'd7b5cbf065' into clippyup

Browse source
This commit is contained in:
flip1995 2022-06-16 17:39:06 +02:00
parent bd071bf5b2
commit f8f9d01c2a
199 changed files with 4158 additions and 1931 deletions
Download patch file Download diff file Expand all files Collapse all files

19
book/src/development/infrastructure/README.md Normal file
View file

@ -0,0 +1,19 @@
# Infrastructure
In order to deploy Clippy over `rustup`, some infrastructure is necessary. This
chapter describes the different parts of the Clippy infrastructure that need to
be maintained to make this possible.
The most important part is the sync between the `rust-lang/rust` repository and
the Clippy repository that takes place every two weeks. This process is
described in the [Syncing changes between Clippy and `rust-lang/rust`](sync.md)
section.
A new Clippy release is done together with every Rust release, so every six
weeks. The release process is described in the [Release a new Clippy
Version](release.md) section. During a release cycle a changelog entry for the
next release has to be written. The format of that and how to do that is
documented in the [Changelog Update](changelog_update.md) section.
> _Note:_ The Clippy CI should also be described in this chapter, but for now is
> left as a TODO.

71
book/src/development/infrastructure/backport.md Normal file
View file

@ -0,0 +1,71 @@
# Backport Changes
Sometimes it is necessary to backport changes to the beta release of Clippy.
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.
## Backport the changes
Backports are done on the beta branch of the Clippy repository.
```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
```
Now you should test that the backport passes all the tests in the Rust
repository. You can do this with:
```bash
# Assuming the current directory corresponds to the Rust repository
$ git checkout beta
$ git subtree pull -p src/tools/clippy https://github.com/<your-github-name>/rust-clippy backport
$ ./x.py test src/tools/clippy
```
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:
```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
```
After this, you can open a PR to the `beta` branch of the Clippy repository.
## Update Clippy in the Rust Repository
This step must be done, **after** the PR of the previous step was merged.
After the backport landed in the Clippy repository, the branch has to be synced
back to the beta branch of the Rust repository.
```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
```
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.

42
book/src/development/infrastructure/book.md Normal file
View file

@ -0,0 +1,42 @@
# The Clippy Book
This document explains how to make additions and changes to the Clippy book, the
guide to Clippy that you're reading right now. The Clippy book is formatted with
[Markdown](https://www.markdownguide.org) and generated by
[mdbook](https://github.com/rust-lang/mdBook).
- [Get mdbook](#get-mdbook)
- [Make changes](#make-changes)
## Get mdbook
While not strictly necessary since the book source is simply Markdown text
files, having mdbook locally will allow you to build, test and serve the book
locally to view changes before you commit them to the repository. You likely
already have `cargo` installed, so the easiest option is to simply:
```shell
cargo install mdbook
```
See the mdbook [installation](https://github.com/rust-lang/mdBook#installation)
instructions for other options.
## Make changes
The book's
[src](https://github.com/joshrotenberg/rust-clippy/tree/clippy_guide/book/src)
directory contains all of the markdown files used to generate the book. If you
want to see your changes in real time, you can use the mdbook `serve` command to
run a web server locally that will automatically update changes as they are
made. From the top level of your `rust-clippy` directory:
```shell
mdbook serve book --open
```
Then navigate to `http://localhost:3000` to see the generated book. While the
server is running, changes you make will automatically be updated.
For more information, see the mdbook
[guide](https://rust-lang.github.io/mdBook/).

102
book/src/development/infrastructure/changelog_update.md Normal file
View file

@ -0,0 +1,102 @@
# Changelog Update
If you want to help with updating the [changelog], you're in the right place.
## When to update
Typos and other small fixes/additions are _always_ welcome.
Special care needs to be taken when it comes to updating the changelog for a new
Rust release. For that purpose, the changelog is ideally updated during the week
before an upcoming stable release. You can find the release dates on the [Rust
Forge][forge].
Most of the time we only need to update the changelog for minor Rust releases.
It's been very rare that Clippy changes were included in a patch release.
## Changelog update walkthrough
### 1. Finding the relevant Clippy commits
Each Rust release ships with its own version of Clippy. The Clippy subtree can
be found in the `tools` directory of the Rust repository.
Depending on the current time and what exactly you want to update, the following
bullet points might be helpful:
* When writing the release notes for the **upcoming stable release** you need to
check out the Clippy commit of the current Rust `beta` branch.
[Link][rust_beta_tools]
* When writing the release notes for the **upcoming beta release**, you need to
check out the Clippy commit of the current Rust `master`.
[Link][rust_master_tools]
* When writing the (forgotten) release notes for a **past stable release**, you
need to check out the Rust release tag of the stable release.
[Link][rust_stable_tools]
Usually you want to write the changelog of the **upcoming stable release**. Make
sure though, that `beta` was already branched in the Rust repository.
To find the commit hash, issue the following command when in a `rust-lang/rust`
checkout:
```
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"
```
### 2. Fetching the PRs between those commits
Once you've got the correct commit range, run
```
util/fetch_prs_between.sh commit1 commit2 > changes.txt
```
and open that file in your editor of choice.
When updating the changelog it's also a good idea to make sure that `commit1` is
already correct in the current changelog.
### 3. Authoring the final changelog
The above script should have dumped all the relevant PRs to the file you
specified. It should have filtered out most of the irrelevant PRs already, but
it's a good idea to do a manual cleanup pass where you look for more irrelevant
PRs. If you're not sure about some PRs, just leave them in for the review and
ask for feedback.
With the PRs filtered, you can start to take each PR and move the `changelog: `
content to `CHANGELOG.md`. Adapt the wording as you see fit but try to keep it
somewhat coherent.
The order should roughly be:
1. New lints
2. Moves or deprecations of lints
3. Changes that expand what code existing lints cover
4. False positive fixes
5. Suggestion fixes/improvements
6. ICE fixes
7. Documentation improvements
8. Others
As section headers, we use:
```
### New Lints
### Moves and Deprecations
### Enhancements
### False Positive Fixes
### Suggestion Fixes/Improvements
### ICE Fixes
### Documentation Improvements
### Others
```
Please also be sure to update the Beta/Unreleased sections at the top with the
relevant commit ranges.
[changelog]: https://github.com/rust-lang/rust-clippy/blob/master/CHANGELOG.md
[forge]: https://forge.rust-lang.org/
[rust_master_tools]: https://github.com/rust-lang/rust/tree/master/src/tools/clippy
[rust_beta_tools]: https://github.com/rust-lang/rust/tree/beta/src/tools/clippy
[rust_stable_tools]: https://github.com/rust-lang/rust/releases

142
book/src/development/infrastructure/release.md Normal file
View file

@ -0,0 +1,142 @@
# Release a new Clippy Version
> _NOTE:_ This document is probably only relevant to you, if you're a member of
> the Clippy team.
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.
[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.
To find out if this step is necessary run
```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
```
If this command outputs `master`, this step is **not** necessary.
```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
```
After this, open a PR to the master branch. In this PR, the commit hash of the
`HEAD` of the `beta` branch must exists. In addition to that, no files should be
changed by this PR.
## Update the `beta` branch
This step must be done **after** the PR of the previous step was merged.
First, the Clippy commit of the `beta` branch of the Rust repository has to be
determined.
```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")
```
After finding the Clippy commit, 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 push upstream beta
```
## Find the Clippy commit
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.
```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")
```
## Tag the stable commit
After finding the Clippy commit, it can be tagged with the release number.
```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
```
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].
If you don't have time to do a complete changelog update right away, just update
the following parts:
- Remove the `(beta)` from the new stable version:
```markdown
## Rust 1.XX (beta) -> ## Rust 1.XX
```
- Update the release date line of the new stable version:
```markdown
Current beta, release 20YY-MM-DD -> Current stable, released 20YY-MM-DD
```
- Update the release date line of the previous stable version:
```markdown
Current stable, released 20YY-MM-DD -> Released 20YY-MM-DD
```
[how to update the changelog]: changelog_update.md

123
book/src/development/infrastructure/sync.md Normal file
View file

@ -0,0 +1,123 @@
# Syncing changes between Clippy and [`rust-lang/rust`]
Clippy currently gets built with a pinned nightly version.
In the `rust-lang/rust` repository, where rustc resides, there's a copy of
Clippy that compiler hackers modify from time to time to adapt to changes in the
unstable API of the compiler.
We need to sync these changes back to this repository periodically, and the
changes made to this repository in the meantime also need to be synced to the
`rust-lang/rust` repository.
To avoid flooding the `rust-lang/rust` PR queue, this two-way sync process is
done in a bi-weekly basis if there's no urgent changes. This is done starting on
the day of the Rust stable release and then every other week. That way we
guarantee that we keep this repo up to date with the latest compiler API, and
every feature in Clippy is available for 2 weeks in nightly, before it can get
to beta. For reference, the first sync following this cadence was performed the
2020-08-27.
This process is described in detail in the following sections. For general
information about `subtree`s in the Rust repository see [Rust's
`CONTRIBUTING.md`][subtree].
## Patching git-subtree to work with big repos
Currently, there's a bug in `git-subtree` that prevents it from working properly
with the [`rust-lang/rust`] repo. There's an open PR to fix that, but it's
stale. Before continuing with the following steps, we need to manually apply
that fix to our local copy of `git-subtree`.
You can get the patched version of `git-subtree` from [here][gitgitgadget-pr].
Put this file under `/usr/lib/git-core` (making a backup of the previous file)
and make sure it has the proper permissions:
```bash
sudo cp --backup /path/to/patched/git-subtree.sh /usr/lib/git-core/git-subtree
sudo chmod --reference=/usr/lib/git-core/git-subtree~ /usr/lib/git-core/git-subtree
sudo chown --reference=/usr/lib/git-core/git-subtree~ /usr/lib/git-core/git-subtree
```
> _Note:_ The first time running `git subtree push` a cache has to be built.
> This involves going through the complete Clippy history once. For this you
> have to increase the stack limit though, which you can do with `ulimit -s
> 60000`. Make sure to run the `ulimit` command from the same session you call
> git subtree.
> _Note:_ If you are a Debian user, `dash` is the shell used by default for
> scripts instead of `sh`. This shell has a hardcoded recursion limit set to
> 1000. In order to make this process work, you need to force the script to run
> `bash` instead. You can do this by editing the first line of the `git-subtree`
> script and changing `sh` to `bash`.
## Defining remotes
You may want to define remotes, so you don't have to type out the remote
addresses on every sync. You can do this with the following commands (these
commands still have to be run inside the `rust` directory):
```bash
# Set clippy-upstream remote for pulls
$ git remote add clippy-upstream https://github.com/rust-lang/rust-clippy
# Make sure to not push to the upstream repo
$ git remote set-url --push clippy-upstream DISABLED
# Set a local remote
$ git remote add clippy-local /path/to/rust-clippy
```
> Note: The following sections assume that you have set those remotes with the
> above remote names.
## Performing the sync from [`rust-lang/rust`] to Clippy
Here is a TL;DR version of the sync process (all of the following commands have
to be run inside the `rust` directory):
1. Clone the [`rust-lang/rust`] repository or make sure it is up to date.
2. Checkout the commit from the latest available nightly. You can get it using
`rustup check`.
3. Sync the changes to the rust-copy of Clippy to your Clippy fork:
```bash
# Make sure to change `your-github-name` to your github name in the following command. Also be
# sure to either use a net-new branch, e.g. `sync-from-rust`, or delete the branch beforehand
# because changes cannot be fast forwarded and you have to run this command again.
git subtree push -P src/tools/clippy clippy-local sync-from-rust
```
> _Note:_ Most of the time you have to create a merge commit in the
> `rust-clippy` repo (this has to be done in the Clippy repo, not in the
> rust-copy of Clippy):
```bash
git fetch upstream # assuming upstream is the rust-lang/rust remote
git checkout sync-from-rust
git merge upstream/master --no-ff
```
> Note: This is one of the few instances where a merge commit is allowed in
> a PR.
4. Bump the nightly version in the Clippy repository by changing the date in the
rust-toolchain file to the current date and committing it with the message:
```bash
git commit -m "Bump nightly version -> YYYY-MM-DD"
```
5. Open a PR to `rust-lang/rust-clippy` and wait for it to get merged (to
accelerate the process ping the `@rust-lang/clippy` team in your PR and/or
ask them in the [Zulip] stream.)
[Zulip]: https://rust-lang.zulipchat.com/#narrow/stream/clippy
## Performing the sync from Clippy to [`rust-lang/rust`]
All of the following commands have to be run inside the `rust` directory.
1. Make sure you have checked out the latest `master` of `rust-lang/rust`.
2. Sync the `rust-lang/rust-clippy` master to the rust-copy of Clippy:
```bash
git checkout -b sync-from-clippy
git subtree pull -P src/tools/clippy clippy-upstream master
```
3. Open a PR to [`rust-lang/rust`]
[gitgitgadget-pr]: https://github.com/gitgitgadget/git/pull/493
[subtree]: https://rustc-dev-guide.rust-lang.org/contributing.html#external-dependencies-subtree
[`rust-lang/rust`]: https://github.com/rust-lang/rust