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