mirror of
https://github.com/getpaseo/paseo.git
synced 2026-11-11 02:46:29 +00:00
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:
+30
-9
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user