1# Changelog Update
2
3If you want to help with updating the [changelog][changelog], you're in the right place.
4
5## When to update
6
7Typos and other small fixes/additions are _always_ welcome.
8
9Special care needs to be taken when it comes to updating the changelog for a new
10Rust release. For that purpose, the changelog is ideally updated during the week
11before an upcoming stable release. You can find the release dates on the [Rust
12Forge][forge].
13
14Most of the time we only need to update the changelog for minor Rust releases. It's
15been 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
21Each Rust release ships with its own version of Clippy. The Clippy subtree can
22be found in the `tools` directory of the Rust repository.
23
24Depending on the current time and what exactly you want to update, the following
25bullet 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
35Usually you want to wirte the changelog of the **upcoming stable release**. Make
36sure though, that `beta` was already branched in the Rust repository.
37
38To find the commit hash, issue the following command when in a `rust-lang/rust` checkout:
39```
40git 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
45Once you've got the correct commit range, run
46
47    util/fetch_prs_between.sh commit1 commit2 > changes.txt
48
49and open that file in your editor of choice.
50
51When updating the changelog it's also a good idea to make sure that `commit1` is
52already correct in the current changelog.
53
54### 3. Authoring the final changelog
55
56The above script should have dumped all the relevant PRs to the file you
57specified. It should have filtered out most of the irrelevant PRs
58already, but it's a good idea to do a manual cleanup pass where you look for
59more irrelevant PRs. If you're not sure about some PRs, just leave them in for
60the review and ask for feedback.
61
62With 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
64try to keep it somewhat coherent.
65
66The order should roughly be:
67
681. New lints
692. Moves or deprecations of lints
703. Changes that expand what code existing lints cover
714. False positive fixes
725. Suggestion fixes/improvements
736. ICE fixes
747. Documentation improvements
758. Others
76
77As 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
90Please also be sure to update the Beta/Unreleased sections at the top with the
91relevant 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
98