Skip to content
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.

Commit 3e1dd20

Browse files
committedMar 30, 2020
Auto merge of #5373 - flip1995:doc_release_backport, r=Manishearth
Document how to create releases and backports This PR adds documentation on how to create Clippy releases and backports. This PR also introduces a new backport/release process for Clippy: - A beta branch is introduced: https://github.com/rust-lang/rust-clippy/tree/beta - Backports are now done by PRs to the `beta` branch - also commits to the beta branch will be deployed, so that the documentation page has a tab for the Clippy beta release. This has two advantages: 1. The Clippy release process is closer to the Rust release process: stable releases are tagged, the beta release has its own branch 2. Backports to beta are easier, since they don't need as much coordination as before. No new branch has to be created for a backport. Just a PR to the beta branch, like in the Rust repo.¹ I tested the deployment here: https://github.com/flip1995/rust-clippy/runs/534465081 and it created this commit: flip1995@7345033, so it works. r? @Manishearth your thoughts? [Rendered (release.md)](https://github.com/flip1995/rust-clippy/blob/doc_release_backport/doc/release.md) [Rendered (backport.md)](https://github.com/flip1995/rust-clippy/blob/doc_release_backport/doc/backport.md) changelog: none --- ¹: For this, we may have to modify the CI, so that beta rustc is used to check PRs to beta (or we test it locally, and merge it without bors)
2 parents 563da52 + 2a4493a commit 3e1dd20

File tree

6 files changed

+167
-1
lines changed

6 files changed

+167
-1
lines changed
 

‎.github/deploy.sh

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,11 @@ if [[ -n $TAG_NAME ]]; then
1717
ln -s "$TAG_NAME" out/stable
1818
fi
1919

20+
if [[ $BETA = "true" ]]; then
21+
echo "Update documentation for the beta release"
22+
cp -r out/master out/beta
23+
fi
24+
2025
# Generate version index that is shown as root index page
2126
cp util/gh-pages/versions.html out/index.html
2227

@@ -35,12 +40,15 @@ fi
3540

3641
if [[ -n $TAG_NAME ]]; then
3742
# Add the new dir
38-
git add $TAG_NAME
43+
git add "$TAG_NAME"
3944
# Update the symlink
4045
git add stable
4146
# Update versions file
4247
git add versions.json
4348
git commit -m "Add documentation for ${TAG_NAME} release: ${SHA}"
49+
elif [[ $BETA = "true" ]]; then
50+
git add beta
51+
git commit -m "Automatic deploy to GitHub Pages (beta): ${SHA}"
4452
else
4553
git add .
4654
git commit -m "Automatic deploy to GitHub Pages: ${SHA}"

‎.github/workflows/deploy.yml

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ on:
44
push:
55
branches:
66
- master
7+
- beta
78
tags:
89
- rust-1.**
910

@@ -34,6 +35,9 @@ jobs:
3435
run: |
3536
TAG=$(basename ${{ github.ref }})
3637
echo "::set-env name=TAG_NAME::$TAG"
38+
- name: Set beta to true
39+
if: github.ref == 'refs/heads/beta'
40+
run: echo "::set-env name=BETA::true"
3741
- name: Deploy
3842
run: |
3943
eval "$(ssh-agent -s)"

‎doc/backport.md

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
# Backport Changes
2+
3+
Sometimes it is necessary to backport changes to the beta release of Clippy.
4+
Backports in Clippy are rare and should be approved by the Clippy team. For
5+
example, a backport is done, if a crucial ICE was fixed or a lint is broken to a
6+
point, that it has to be disabled, before landing on stable.
7+
8+
Backports are done to the `beta` release 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.
11+
12+
13+
## Backport the changes
14+
15+
Backports are done on the beta branch of the Clippy repository.
16+
17+
```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, that should be backported
22+
$ git push origin backport
23+
```
24+
25+
After this, you can open a PR to the `beta` branch of the Clippy repository.
26+
27+
28+
## Update Clippy in the Rust Repository
29+
30+
This step must be done, **after** the PR of the previous step was merged.
31+
32+
After the backport landed in the Clippy repository, also the Clippy version on
33+
the Rust `beta` branch has to be updated.
34+
35+
```bash
36+
# Assuming the current directory corresponds to the Rust repository
37+
$ git checkout beta
38+
$ git checkout -b clippy_backport
39+
$ pushd src/tools/clippy
40+
$ git fetch
41+
$ git checkout beta
42+
$ popd
43+
$ git add src/tools/clippy
44+
§ git commit -m "Update Clippy"
45+
$ git push origin clippy_backport
46+
```
47+
48+
After this you can open a PR to the `beta` branch of the Rust repository. In
49+
this PR you should tag the Clippy team member, that agreed to the backport or
50+
the `@rust-lang/clippy` team. Make sure to add `[beta]` to the title of the PR.

‎doc/release.md

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
# Release a new Clippy Version
2+
3+
_NOTE: This document is probably only relevant to you, if you're a member of the
4+
Clippy team._
5+
6+
Clippy is released together with stable Rust releases. The dates for these
7+
releases can be found at the [Rust Forge]. This document explains the necessary
8+
steps to create a Clippy release.
9+
10+
1. [Find the Clippy commit](#find-the-clippy-commit)
11+
2. [Tag the stable commit](#tag-the-stable-commit)
12+
3. [Update `CHANGELOG.md`](#update-changelogmd)
13+
4. [Remerge the `beta` branch](#remerge-the-beta-branch)
14+
5. [Update the `beta` branch](#update-the-beta-branch)
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._
18+
19+
[Rust Forge]: https://forge.rust-lang.org/
20+
21+
22+
## Find the Clippy commit
23+
24+
The first step is to tag the Clippy commit, that is included in the stable Rust
25+
release. This commit can be found in the Rust repository.
26+
27+
```bash
28+
# Assuming the current directory corresponds to the Rust repository
29+
$ git fetch upstream # `upstream` is the `rust-lang/rust` remote
30+
$ git checkout 1.XX.0 # XX should be exchanged with the corresponding version
31+
$ git submodule update
32+
$ SHA=$(git submodule status src/tools/clippy | awk '{print $1}')
33+
```
34+
35+
36+
## Tag the stable commit
37+
38+
After finding the Clippy commit, it can be tagged with the release number.
39+
40+
```bash
41+
# Assuming the current directory corresponds to the Clippy repository
42+
$ git checkout $SHA
43+
$ git tag rust-1.XX.0 # XX should be exchanged with the corresponding version
44+
$ git push upstream master --tags # `upstream` is the `rust-lang/rust-clippy` remote
45+
```
46+
47+
After this, the release should be available on the Clippy [release page].
48+
49+
[release page]: https://github.com/rust-lang/rust-clippy/releases
50+
51+
52+
## Update `CHANGELOG.md`
53+
54+
For this see the document on [how to update the changelog].
55+
56+
[how to update the changelog]: https://github.com/rust-lang/rust-clippy/blob/master/doc/changelog_update.md
57+
58+
59+
## Remerge the `beta` branch
60+
61+
This step is only necessary, if since the last release something was backported
62+
to the beta Rust release. The remerge is then necessary, to make sure that the
63+
Clippy commit, that was used by the now stable Rust release, persists in the
64+
tree of the Clippy repository.
65+
66+
```bash
67+
# Assuming `HEAD` is the current `master` branch of rust-lang/rust-clippy
68+
$ git checkout -b backport_remerge
69+
$ git merge beta
70+
$ git diff # This diff has to be empty, otherwise something with the remerge failed
71+
$ git push origin backport_remerge # This can be pushed to your fork
72+
```
73+
74+
After this, open a PR to the master branch. In this PR, the commit hash of the
75+
`HEAD` of the `beta` branch must exists. In addition to that, no files should
76+
be changed by this PR.
77+
78+
79+
## Update the `beta` branch
80+
81+
This step must be done **after** the PR of the previous step was merged.
82+
83+
First, the Clippy commit of the `beta` branch of the Rust repository has to be
84+
determined.
85+
86+
```bash
87+
# Assuming the current directory corresponds to the Rust repository
88+
$ git checkout beta
89+
$ git submodule update
90+
$ BETA_SHA=$(git submodule status src/tools/clippy | awk '{print $1}')
91+
```
92+
93+
After finding the Clippy commit, the `beta` branch in the Clippy repository can
94+
be updated.
95+
96+
```bash
97+
# Assuming the current directory corresponds to the Clippy repository
98+
$ git checkout beta
99+
$ git rebase $BETA_SHA
100+
$ git push upstream beta [-f] # This requires a force push, if a remerge was done
101+
```

‎util/gh-pages/versions.html

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -65,6 +65,7 @@ <h3 class="panel-title">
6565
$scope.versionOrder = function(v) {
6666
if (v === 'master') { return Infinity; }
6767
if (v === 'stable') { return Number.MAX_VALUE; }
68+
if (v === 'beta') { return Number.MAX_VALUE - 1; }
6869

6970
return $scope.normalizeVersion(v)
7071
.split('.')

‎util/versions.py

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,8 @@ def key(v):
1212
return float('inf')
1313
if v == 'stable':
1414
return sys.maxsize
15+
if v == 'beta':
16+
return sys.maxsize - 1
1517

1618
v = v.replace('v', '').replace('rust-', '')
1719

0 commit comments

Comments
 (0)
Please sign in to comment.