Skip to content

Commit 071f774

Browse files
Mark-SimulacrumBoxyUwU
Mark-Simulacrum
authored and
BoxyUwU
committed
Update release note process for current tooling
1 parent bfed41a commit 071f774

File tree

1 file changed

+152
-15
lines changed

1 file changed

+152
-15
lines changed

‎src/release/release-notes.md

+152-15
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,158 @@
11
# Preparing Release Notes
2-
The release notes for the next release should be compiled at the beginning of
3-
the beta cycle, 6 weeks ahead of the release.
42

5-
Clone the [relnotes] utility. This program pulls all pull requests made against
6-
`rust-lang/rust` and `rust-lang/cargo` within the latest release cycle and
7-
prints out a markdown document containing all the pull requests, categorised
8-
into their respective sections where possible, and prints the document to
9-
`stdout`.
3+
This document discusses the process for preparing release notes (low level
4+
changelog) and the blog post (high level changelog) announcing the Rust
5+
releases.
106

11-
Only pull requests that impact stable users of Rust should be included.
12-
Generally, more exciting items go toward the top of sections. Most items are
13-
simply links to the PR that landed them; some that need more explanation have
14-
additional, unlinked text; anything supported by an RFC has an additional RFC
15-
link. Reuse the PR titles or write descriptions as needed for clarity.
7+
## Automation/community: Step 1: PR or issue is labeled for release note consideration
168

17-
Try to keep the language of the document independent of en-US or en-UK, when it
18-
can't be avoided defer to en-US grammar and syntax.
9+
This step happens for `relnotes`, `relnotes-perf`, and `finished-final-comment-period`
10+
labels in rust-lang/rust and is managed by triagebot
11+
([implementation](https://github.com/rust-lang/triagebot/blob/38b904f010338e3847bf1eba651356985c6f1df1/src/handlers/relnotes.rs#L67)).
1912

20-
[relnotes]: https://github.com/rust-lang/relnotes
13+
Note that this step happens **on labeling**, not necessarily when the issue/PR
14+
is merged/closed. (FIXME: Should we move this to close time, to make it more
15+
likely that authors see the relnotes issue when it's warranted, particularly
16+
for tracking issues?).
17+
18+
## Automation/community: Step 2: Blog post or release note text is proposed
19+
20+
Once labeled, a new issue is automatically filed with title "Tracking issue for
21+
release notes of #xxxx: $original pr title". This is labeled with relnotes +
22+
relnotes-tracking-issue.
23+
24+
The Rust team responsible for the area and/or contributors making the PR can
25+
(should) use this issue to propose any release note text. The issue contains a
26+
code block for the release note contents (to go into RELNOTES.md) and for the blog.
27+
28+
Ideally, text is directly edited into the code block, but if permissions aren't
29+
available discussion can happen on the thread and will be absorbed by the
30+
release team later.
31+
32+
The release note text is automatically pulled in subsequent steps, and should use headers from [this list] if possible:
33+
34+
[this list]: https://github.com/rust-lang/relnotes/blob/33e78d703a439c8721705b26e2613ec6dac0cb4f/src/main.rs#L444-L449
35+
36+
* Compatibility Notes
37+
* Library
38+
* Language
39+
* Compiler
40+
* Internal Changes
41+
* Other
42+
43+
## Release team: Step 3: Confirm all issues/PRs needing relnotes are labeled `relnotes`
44+
45+
This steps should happen in the first 3 weeks of the beta period (earlier is
46+
better). This can be done with help from the wider Rust project too.
47+
48+
[Search] for `is:pr milestone:1.85.0 is:merged -label:relnotes -label:relnotes-perf -label:finished-final-comment-period` in GitHub on rust-lang/rust PRs, updating the milestone appropriately.
49+
50+
This should find all merged PRs that haven't already been nominated. Typically
51+
there are several hundred of them; the goal is to try to find anything that
52+
jumps out as *should have been nominated* and nominate it by tagging with
53+
relnotes. Scrolling through the list without clicking through and using the
54+
GitHub checkbox UI to mass-label issues is a good strategy.
55+
56+
The goal here is mostly **catching obvious things**, not 100% exhaustiveness.
57+
It's generally OK if we miss something. If there's a consistent pattern, note
58+
it down for inclusion in triagebot's automatic issue filing.
59+
60+
[Search]: https://github.com/rust-lang/rust/pulls?q=is%3Apr+milestone%3A1.85.0+is%3Amerged+-label%3Arelnotes+-label%3Arelnotes-perf+-label%3Afinished-final-comment-period
61+
62+
FIXME: This step may also need to include an attempt to milestone any
63+
**issues** that got tagged relnotes and closed -- those currently don't get
64+
milestones associated with them, which means their corresponding relnotes
65+
tracking issue is probably never included (letting it get missed indefinitely).
66+
67+
FIXME: Process for Compatibility Notes?
68+
69+
## Release team: Step 4: Release notes generation starts
70+
71+
This steps should happen in the first 3 weeks of the beta period (earlier is
72+
better). The release team owner for the current release will run the [relnotes]
73+
tool.
74+
75+
```shell
76+
cargo build
77+
GITHUB_TOKEN=$(gh auth token) cargo run --bin relnotes -- 1.85.0 > relnotes.md
78+
```
79+
80+
This produces console output (stderr) like this:
81+
82+
```text
83+
Did not use "Libraries" from Tracking issue for release notes of #132515: Fix and undeprecate home_dir() <https://github.com/rust-lang/rust/issues/132650>
84+
Did not use "Stabilized APIs" from Tracking issue for release notes of #67521: Tracking issue for const `alloc::Layout` <https://github.com/rust-lang/rust/issues/134725>
85+
Did not use "Category (e.g. Language, Compiler, Libraries, Compatibility notes, ...)" from Tracking issue for release notes of #132187: Add Extend impls for tuples of arity 1 through 12 <https://github.com/rust-lang/rust/issues/133975>
86+
```
2187

88+
These lines typically mean that someone either hasn't updated or used a keyword not in the list above, for example:
89+
90+
* Libraries should be Library
91+
* Stabilized APIs is not yet supported (FIXME!)
92+
* Category ... needs updating.
93+
94+
The runner of the tool should go update these issues with the right contents
95+
(e.g., renaming/categorizing). The **source of truth** is the issue, not the
96+
local output of the tool -- this is important as we want to automate tool
97+
execution in the long run, so try to minimize the amount of local edits done on
98+
the resulting `relnotes.md`.
99+
100+
The tool's standard output is directed to `relnotes.md` above, which will
101+
currently contain formatted headers for each of the sections with content
102+
pulled from the "Tracking issue for ..." **or** standard content (PR/issue
103+
title + link) if there is no "tracking issue for ..." found by the tool.
104+
105+
If an issue is missing, see Step 3 (tag it and re-run the tool). If an issue is
106+
present *but shouldn't be*, the best thing is to tag it with relnotes (or find
107+
the pre-existing relnotes tracking issue) and *close that tracking issue*. This
108+
will also drop the item from the tool's output.
109+
110+
## Release team: Step 5: Publish relnotes PR
111+
112+
See example from 1.84: https://github.com/rust-lang/rust/pull/134568
113+
114+
Take the `relnotes.md` you have locally (typically without library
115+
stabilizations in today's world, you'll add them at a later point -- we want
116+
the copy without them as early as possible), and insert it at the top of
117+
RELEASES.md in rust-lang/rust, and open a new PR with those contents. You can
118+
`r?` the owner for actually publishing the release for this cycle and cc the
119+
release team.
120+
121+
Include a link to this document (https://forge.rust-lang.org/release/release-notes.html)
122+
in the PR description, pointing at step 6 (i.e., prefer suggesting updates not on the PR).
123+
124+
The next release team meeting should also discuss this PR for selecting blog
125+
post topics (see below for blog post process).
126+
127+
## All: Step 6: Incorporate edits from relnotes PR
128+
129+
You'll typically get a lot (several dozen) of comments on the PR with typo
130+
fixes, suggestions for alternative text, etc. A good strategy is to try to
131+
update the originating issues for issues/PRs (or file them and update them),
132+
essentially matching the iteration already done locally in step 4. The longer
133+
state stays in issues the easier it is to notice and incorporate updates from
134+
those into the PR (just rerun the tool).
135+
136+
Pushing edits into the issues helps bring the right people (e.g., PR
137+
author/reviewer) into the loop on what is getting discussed.
138+
139+
## Release team: Step 7: Close tracking issues
140+
141+
At some point, the release team owner should declare the PR authoritative and
142+
close all relnotes tracking issues associated with the current milestone ([sample search](https://github.com/rust-lang/rust/issues?q=is%3Aissue%20state%3Aopen%20milestone%3A1.85.0%20label%3Arelnotes-tracking-issue)). Doing this in the GitHub UI is easiest.
143+
144+
FIXME: Ideally those would all get linked from the relnotes PR, so it's easier
145+
to go back and forth between them.
146+
147+
# Blog post process
148+
149+
After publishing the release notes PR, the release team's next meeting will
150+
discuss what blog post topics we want. Typically this is a pretty informal
151+
discussion and isn't necessarily final; the goal is to provide input into the
152+
blog post author's choice by providing more perspectives.
153+
154+
The blog post author will then aim to post the blog post PR as soon as possible
155+
(typically 3-7 days out from the release, though we've had shorter turn arounds
156+
too), where it will get reviewed, edited, and finally merged on the release day.
157+
158+
[relnotes]: https://github.com/rust-lang/relnotes

0 commit comments

Comments
 (0)