doc/changelog_update.md

   1 # Changelog Update
   2
   3 If you want to help with updating the [changelog][changelog], you're in the right place.
   4
   5 ## When to update
   6
   7 Typos and other small fixes/additions are _always_ welcome.
   8
   9 Special care needs to be taken when it comes to updating the changelog for a new
  10 Rust release. For that purpose, the changelog is ideally updated during the week
  11 before an upcoming stable release. You can find the release dates on the [Rust
  12 Forge][forge].
  13
  14 Most of the time we only need to update the changelog for minor Rust releases. It's
  15 been very rare that Clippy changes were included in a patch release.
  16
  17 ## How to update
  18
  19 ### 1. Finding the relevant Clippy commits
  20
  21 Each Rust release ships with its own version of Clippy. The Clippy submodule can
  22 be found in the [tools][tools] directory of the Rust repository.
  23
  24 To find the Clippy commit hash for a specific Rust release you select the Rust
  25 release tag from the dropdown and then check the commit of the Clippy directory:
  26
  27 ![Explanation of how to find the commit hash](https://user-images.githubusercontent.com/2042399/62846160-1f8b0480-bcce-11e9-9da8-7964ca034e7a.png)
  28
  29 When writing the release notes for the upcoming stable release you want to check
  30 out the commit of the current Rust `beta` tag.
  31
  32 ### 2. Fetching the PRs between those commits
  33
  34 You'll want to run `util/fetch_prs_between.sh commit1 commit2 > changes.txt`
  35 and open that file in your editor of choice.
  36
  37 * `commit1` is the Clippy commit hash of the previous stable release
  38 * `commit2` is the Clippy commit hash of the release you want to write the changelog for.
  39
  40 When updating the changelog it's also a good idea to make sure that `commit1` is
  41 already correct in the current changelog.
  42
  43 ### 3. Authoring the final changelog
  44
  45 The above script should have dumped all the relevant PRs to the file you
  46 specified. It should have filtered out most of the irrelevant PRs
  47 already, but it's a good idea to do a manual cleanup pass where you look for
  48 more irrelevant PRs. If you're not sure about some PRs, just leave them in for
  49 the review and ask for feedback.
  50
  51 With the PRs filtered, you can start to take each PR and move the
  52 `changelog: ` content to `CHANGELOG.md`. Adapt the wording as you see fit but
  53 try to keep it somewhat coherent.
  54
  55 The order should roughly be:
  56
  57 1. New lints
  58 2. Changes that expand what code existing lints cover
  59 3. ICE fixes
  60 4. False positive fixes
  61 5. Suggestion fixes/improvements
  62
  63 Please also be sure to update the Beta/Unreleased sections at the top with the
  64 relevant commit ranges.
  65
  66 [changelog]: https://github.com/rust-lang/rust-clippy/blob/master/CHANGELOG.md
  67 [forge]: https://forge.rust-lang.org/
  68 [tools]: https://github.com/rust-lang/rust/tree/master/src/tools