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: 734503377e, 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)

.github/deploy.sh

@@ -17,6 +17,11 @@ if [[ -n $TAG_NAME ]]; then
   ln -s "$TAG_NAME" out/stable
 fi
 
+if [[ $BETA = "true" ]]; then
+  echo "Update documentation for the beta release"
+  cp -r out/master out/beta
+fi
+
 # Generate version index that is shown as root index page
 cp util/gh-pages/versions.html out/index.html
 
@@ -35,12 +40,15 @@ fi
 
 if [[ -n $TAG_NAME ]]; then
   # Add the new dir
-  git add $TAG_NAME
+  git add "$TAG_NAME"
   # Update the symlink
   git add stable
   # Update versions file
   git add versions.json
   git commit -m "Add documentation for ${TAG_NAME} release: ${SHA}"
+elif [[ $BETA = "true" ]]; then
+  git add beta
+  git commit -m "Automatic deploy to GitHub Pages (beta): ${SHA}"
 else
   git add .
   git commit -m "Automatic deploy to GitHub Pages: ${SHA}"

.github/workflows/deploy.yml

@@ -4,6 +4,7 @@ on:
   push:
     branches:
       - master
+      - beta
     tags:
       - rust-1.**
 
@@ -34,6 +35,9 @@ jobs:
       run: |
         TAG=$(basename ${{ github.ref }})
         echo "::set-env name=TAG_NAME::$TAG"
+    - name: Set beta to true
+      if: github.ref == 'refs/heads/beta'
+      run: echo "::set-env name=BETA::true"
     - name: Deploy
       run: |
         eval "$(ssh-agent -s)"

doc/backport.md

@@ -0,0 +1,50 @@
+# 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` release 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, that should be backported
+$ 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, also the Clippy version on
+the Rust `beta` branch has to be updated.
+
+```bash
+# Assuming the current directory corresponds to the Rust repository
+$ git checkout beta
+$ git checkout -b clippy_backport
+$ pushd src/tools/clippy
+$ git fetch
+$ git checkout beta
+$ popd
+$ git add src/tools/clippy
+§ git commit -m "Update Clippy"
+$ git push origin clippy_backport
+```
+
+After this you can 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.

doc/release.md

@@ -0,0 +1,101 @@
+# 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. [Find the Clippy commit](#find-the-clippy-commit)
+2. [Tag the stable commit](#tag-the-stable-commit)
+3. [Update `CHANGELOG.md`](#update-changelogmd)
+4. [Remerge the `beta` branch](#remerge-the-beta-branch)
+5. [Update the `beta` branch](#update-the-beta-branch)
+
+_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/
+
+
+## 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
+$ git submodule update
+$ SHA=$(git submodule status src/tools/clippy | awk '{print $1}')
+```
+
+
+## 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 master --tags   # `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 `CHANGELOG.md`
+
+For this see the document on [how to update the changelog].
+
+[how to update the changelog]: https://github.com/rust-lang/rust-clippy/blob/master/doc/changelog_update.md
+
+
+## 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.
+
+```bash
+# Assuming `HEAD` is the current `master` branch of rust-lang/rust-clippy
+$ git checkout -b backport_remerge
+$ git merge 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 checkout beta
+$ git submodule update
+$ BETA_SHA=$(git submodule status src/tools/clippy | awk '{print $1}')
+```
+
+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 rebase $BETA_SHA
+$ git push upstream beta [-f]   # This requires a force push, if a remerge was done
+```

util/gh-pages/versions.html

@@ -65,6 +65,7 @@
             $scope.versionOrder = function(v) {
                 if (v === 'master') { return Infinity; }
                 if (v === 'stable') { return Number.MAX_VALUE; }
+                if (v === 'beta') { return Number.MAX_VALUE - 1; }
 
                 return $scope.normalizeVersion(v)
                     .split('.')

util/versions.py

@@ -12,6 +12,8 @@ def key(v):
         return float('inf')
     if v == 'stable':
         return sys.maxsize
+    if v == 'beta':
+        return sys.maxsize - 1
 
     v = v.replace('v', '').replace('rust-', '')