From 8d24facccbccd893176c38e7fc8460a22f860774 Mon Sep 17 00:00:00 2001 From: Philipp Hansch <dev@phansch.net> Date: Sun, 11 Aug 2019 09:24:03 +0200 Subject: [PATCH 1/4] docs: Explain how to update the changelog --- CHANGELOG.md | 2 ++ doc/changelog_update.md | 59 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 61 insertions(+) create mode 100644 doc/changelog_update.md diff --git a/CHANGELOG.md b/CHANGELOG.md index e4a1a602c43..ec8e8929bfd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,8 @@ # Change Log All notable changes to this project will be documented in this file. +See [Changelog Update](doc/changelog_update.md) if you want to update this +document. ## Unreleased / In Rust Beta or Nightly diff --git a/doc/changelog_update.md b/doc/changelog_update.md new file mode 100644 index 00000000000..b54143e2357 --- /dev/null +++ b/doc/changelog_update.md @@ -0,0 +1,59 @@ +# Changelog Update + +If you want to help with updating the [changelog][changelog], you're in the right place. + +## When to update + +The changelog is ideally updated during the week before an upcoming stable +release. Typos and other small fixes/additions are always welcome. 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. + +## How to update + +### 1. Finding the relevant Clippy commits + +Each Rust release ships with its own version of Clippy. The Clippy submodule can +be found in the [tools][tools] directory of the Rust repository. + +To find the Clippy commit hash for a specific Rust release you select the Rust +release tag from the dropdown and then check the commit of the Clippy directory: + +TODO: Include screenshot + +### 2. Fetching the PRs between those commits + +You'll want to run `util/fetch_prs_between.sh commit1 commit2 > changes.txt` +and open that file in your editor of choice. + +* `commit1` is the Clippy commit hash of the previous stable release +* `commit2` is the Clippy commit hash of the release you want to write the changelog for. + +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 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. Changes that expand what code existing lints cover +3. ICE fixes +4. False positive fixes +5. Suggestion fixes/improvements + +[changelog]: https://github.com/rust-lang/rust-clippy/blob/master/CHANGELOG.md +[forge]: https://forge.rust-lang.org/ +[tools]: https://github.com/rust-lang/rust/tree/master/src/tools From c90eb4f4b3778a3b3d1e3c804dfce279380bf6f1 Mon Sep 17 00:00:00 2001 From: Philipp Hansch <dev@phansch.net> Date: Mon, 12 Aug 2019 06:56:54 +0200 Subject: [PATCH 2/4] Add image --- doc/changelog_update.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/changelog_update.md b/doc/changelog_update.md index b54143e2357..2198029bf78 100644 --- a/doc/changelog_update.md +++ b/doc/changelog_update.md @@ -21,7 +21,7 @@ be found in the [tools][tools] directory of the Rust repository. To find the Clippy commit hash for a specific Rust release you select the Rust release tag from the dropdown and then check the commit of the Clippy directory: -TODO: Include screenshot + ### 2. Fetching the PRs between those commits From 38c1971b435ce67d2f47960dcb7dbf03a3d67447 Mon Sep 17 00:00:00 2001 From: Philipp Hansch <dev@phansch.net> Date: Mon, 12 Aug 2019 19:19:46 +0200 Subject: [PATCH 3/4] Further text improvements --- doc/changelog_update.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/doc/changelog_update.md b/doc/changelog_update.md index 2198029bf78..4eb97b48b9c 100644 --- a/doc/changelog_update.md +++ b/doc/changelog_update.md @@ -4,9 +4,12 @@ If you want to help with updating the [changelog][changelog], you're in the righ ## When to update -The changelog is ideally updated during the week before an upcoming stable -release. Typos and other small fixes/additions are always welcome. You can find -the release dates on the [Rust Forge][forge]. +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. @@ -42,7 +45,7 @@ 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 PRs filtered, you can start to take each PR and move the +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. @@ -54,6 +57,9 @@ The order should roughly be: 4. False positive fixes 5. Suggestion fixes/improvements +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/ [tools]: https://github.com/rust-lang/rust/tree/master/src/tools From a0f9af2132e6dec27be80bd94abc0f2cfe22218e Mon Sep 17 00:00:00 2001 From: Philipp Hansch <dev@phansch.net> Date: Wed, 21 Aug 2019 07:23:48 +0200 Subject: [PATCH 4/4] Add note on how to find the latest beta commit --- doc/changelog_update.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/doc/changelog_update.md b/doc/changelog_update.md index 4eb97b48b9c..cabf25135da 100644 --- a/doc/changelog_update.md +++ b/doc/changelog_update.md @@ -26,6 +26,9 @@ release tag from the dropdown and then check the commit of the Clippy directory:  +When writing the release notes for the upcoming stable release you want to check +out the commit of the current Rust `beta` tag. + ### 2. Fetching the PRs between those commits You'll want to run `util/fetch_prs_between.sh commit1 commit2 > changes.txt`