docs(release): say how changelog highlights are ranked

The highlight order of 0.16.0-beta.1 was wrong twice: first in the order the pull requests were collected, then with the maintainer's four named items on top in the order they were typed, which pushed Background tasks to fifth. The doc only said "biggest first", so there was no test to apply.

Changelog ordering now owns the ranking: reach and frequency, four groups, and what to do with a maintainer correction. The entry puts Background tasks back at the top; no wording changes.
This commit is contained in:
Mohamed Boudra
2026-11-11 03:03:46 +01:00
parent 8b8957ab77
commit 97d39a0158
3 changed files with 32 additions and 11 deletions
+30 -9
View File
@@ -669,9 +669,9 @@ Every section bullet must be scannable at a glance. The changelog is not release
## Changelog highlights
Every release entry leads with highlights: the changes a user would name first when asked what is
new. They are a list above the first `###` section, biggest first. The sections below are the
full record; a reader who stops after the highlights should have missed nothing they would ask
about.
new. They are a list above the first `###` section, ranked as
[Changelog ordering](#changelog-ordering) describes. The sections below are the full record; a
reader who stops after the highlights should have missed nothing they would ask about.
```markdown
## 0.16.0 - 2026-11-20
@@ -681,10 +681,6 @@ about.
### Added
```
- **Rank by what a user gains.** Changes the maintainer named as the headline lead, in the order
given. After those, a capability that did not exist before comes ahead of one that got faster or
steadier. Reread the bold words top to bottom before shipping: if the order matches the order you
collected the pull requests in, or the alphabet, it has not been ranked.
- **The lead-in names what is new in four words at most.** Bold it, colon inside the bold. A reader
who sees only the bold words should know what this release added or changed. A category lead-in
such as `**Polish:**` gathers several related changes.
@@ -719,7 +715,7 @@ about.
| The same shortcuts as desktop: command center, file picker, new workspace, workspace jumps | The same shortcuts as desktop, including your custom bindings |
Before showing a draft, read only the bold lead-ins top to bottom. Each one must answer "what is
new?" without its description.
new?" without its description, and each must outrank the one below it.
## Changelog attribution
@@ -752,7 +748,32 @@ Rules:
## Changelog ordering
Highlights come first, ordered by user impact. Entries within each section (Added, Improved, Fixed) follow the same order:
Rank highlights by how much of a user's day the change touches: how many users get it, and how
often they meet it. Put every highlight in one of four groups, then order each group by the same
question.
1. **New capabilities.** Something a user could not see or do in the last release:
`Background tasks`, `Plugin sidebar views`.
2. **Everyday things that got better.** Speed, steadiness and polish in what users already do
every session: `Faster diff loading`, `Polish`.
3. **Changes for part of the audience.** They need a particular device, provider or setup:
`Keyboard shortcuts on mobile`, `Touch-sized tablet controls`.
4. **Small conveniences and highlighted fixes.** A user is glad to find them and would not update
for them: `Undo workspace archive`, `Fewer reconnects on return`. Fixes are routine, so one
that earned a highlight still follows everything new or improved.
- **Reach decides before kind.** A new capability that needs a hardware keyboard is in group 3.
- **Rank the whole list in one pass.** The order you collected the pull requests in, the alphabet
and the order of the sections below are not rankings.
- **Show the groups with the draft.** List each highlight under its group when you ask for
approval, so the maintainer corrects the test and not one position.
- **A maintainer's note that a change is big moves that change up.** It does not rank the changes
it names against each other, and it does not lower the ones it leaves out.
- **A correction to one highlight is a correction to the test.** Work out which group or question
you got wrong, rank every highlight again, and then edit the file. Moving only the named item
leaves the same mistake in the others.
Bullets within each section (Added, Changed, Fixed) follow this order:
1. **User-facing features and changes first** — things users will notice, want to try, or that change their workflow.
2. **Quality-of-life improvements** — polish, performance, smoother interactions.