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 ## Changelog update walkthrough
  18
  19 ### 1. Finding the relevant Clippy commits
  20
  21 Each Rust release ships with its own version of Clippy. The Clippy subtree can
  22 be found in the `tools` directory of the Rust repository.
  23
  24 Depending on the current time and what exactly you want to update, the following
  25 bullet points might be helpful:
  26
  27 * When writing the release notes for the **upcoming stable release** you need to check
  28   out the Clippy commit of the current Rust `beta` branch. [Link][rust_beta_tools]
  29 * When writing the release notes for the **upcoming beta release**, you need to check
  30   out the Clippy commit of the current Rust `master`. [Link][rust_master_tools]
  31 * When writing the (forgotten) release notes for a **past stable release**, you
  32   need to check out the Rust release tag of the stable release.
  33   [Link][rust_stable_tools]
  34
  35 Usually you want to wirte the changelog of the **upcoming stable release**. Make
  36 sure though, that `beta` was already branched in the Rust repository.
  37
  38 To find the commit hash, issue the following command when in a `rust-lang/rust` checkout:
  39 ```
  40 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"
  41 ```
  42
  43 ### 2. Fetching the PRs between those commits
  44
  45 Once you've got the correct commit range, run
  46
  47     util/fetch_prs_between.sh commit1 commit2 > changes.txt
  48
  49 and open that file in your editor of choice.
  50
  51 When updating the changelog it's also a good idea to make sure that `commit1` is
  52 already correct in the current changelog.
  53
  54 ### 3. Authoring the final changelog
  55
  56 The above script should have dumped all the relevant PRs to the file you
  57 specified. It should have filtered out most of the irrelevant PRs
  58 already, but it's a good idea to do a manual cleanup pass where you look for
  59 more irrelevant PRs. If you're not sure about some PRs, just leave them in for
  60 the review and ask for feedback.
  61
  62 With the PRs filtered, you can start to take each PR and move the
  63 `changelog: ` content to `CHANGELOG.md`. Adapt the wording as you see fit but
  64 try to keep it somewhat coherent.
  65
  66 The order should roughly be:
  67
  68 1. New lints
  69 2. Moves or deprecations of lints
  70 3. Changes that expand what code existing lints cover
  71 4. False positive fixes
  72 5. Suggestion fixes/improvements
  73 6. ICE fixes
  74 7. Documentation improvements
  75 8. Others
  76
  77 As section headers, we use:
  78
  79 ```
  80 ### New Lints
  81 ### Moves and Deprecations
  82 ### Enhancements
  83 ### False Positive Fixes
  84 ### Suggestion Fixes/Improvements
  85 ### ICE Fixes
  86 ### Documentation Improvements
  87 ### Others
  88 ```
  89
  90 Please also be sure to update the Beta/Unreleased sections at the top with the
  91 relevant commit ranges.
  92
  93 [changelog]: https://github.com/rust-lang/rust-clippy/blob/master/CHANGELOG.md
  94 [forge]: https://forge.rust-lang.org/
  95 [rust_master_tools]: https://github.com/rust-lang/rust/tree/master/src/tools/clippy
  96 [rust_beta_tools]: https://github.com/rust-lang/rust/tree/beta/src/tools/clippy
  97 [rust_stable_tools]: https://github.com/rust-lang/rust/releases