]>
Commit | Line | Data |
---|---|---|
f20569fa XL |
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 |