From 97d39a01584baa68447c4d4a850d80fb68288af4 Mon Sep 17 00:00:00 2001
From: Mohamed Boudra <boudra.moha@gmail.com>
Date: Wed, 11 Nov 2026 03:03:46 +0100
Subject: [PATCH] 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.
---
 CHANGELOG.md       |  2 +-
 CHANGELOG.zh-CN.md |  2 +-
 docs/release.md    | 39 ++++++++++++++++++++++++++++++---------
 3 files changed, 32 insertions(+), 11 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 25751013a3..a66fde2adf 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,11 +2,11 @@
 
 ## 0.16.0-beta.1 - 2026-11-10
 
+- **Background tasks:** Paseo now shows the background tasks an agent is running, such as shells and monitors, above the composer, with a Stop button for each. Works with Claude Code, Codex and OpenCode v2. ([#6220](https://github.com/getpaseo/paseo/pull/6220), [#9162](https://github.com/getpaseo/paseo/pull/9162) by [@fxlelouarn](https://github.com/fxlelouarn))
 - **Plugin sidebar views:** A plugin can replace the sidebar's content with its own layout of workspaces, agents, projects and terminals across every connected host. Pick the view per device under Settings → Sidebar; Paseo's sidebar header and footer stay in place. ([#8906](https://github.com/getpaseo/paseo/pull/8906))
 - **Plugin composer controls:** Plugins can add their own controls to the composer, and read and set its prompt, attachments, provider, model, mode and thinking. They can also put the cursor in any agent's composer, add items to New workspace, and store their own metadata on agents and workspaces. ([#8744](https://github.com/getpaseo/paseo/pull/8744), [#9209](https://github.com/getpaseo/paseo/pull/9209), [#9207](https://github.com/getpaseo/paseo/pull/9207))
 - **Faster diff loading:** Opening Changes shows the file tree right away while file contents load. Large diffs arrive in batches, so the rest of the app keeps responding while they load, and diffs take priority over the daemon's background worktree scans. ([#8907](https://github.com/getpaseo/paseo/pull/8907), [#9241](https://github.com/getpaseo/paseo/pull/9241), [#9243](https://github.com/getpaseo/paseo/pull/9243))
 - **Polish:** The chat stays still when a turn ends, and returning to a chat that has not changed shows it as it is with no refresh. Tool rows show their final title and icon from the first frame, the context window popover opens with usage already loaded, and sidebar hover cards open one at a time. ([#8944](https://github.com/getpaseo/paseo/pull/8944), [#9175](https://github.com/getpaseo/paseo/pull/9175), [#9242](https://github.com/getpaseo/paseo/pull/9242), [#9248](https://github.com/getpaseo/paseo/pull/9248), [#9212](https://github.com/getpaseo/paseo/pull/9212), [#9071](https://github.com/getpaseo/paseo/pull/9071))
-- **Background tasks:** Paseo now shows the background tasks an agent is running, such as shells and monitors, above the composer, with a Stop button for each. Works with Claude Code, Codex and OpenCode v2. ([#6220](https://github.com/getpaseo/paseo/pull/6220), [#9162](https://github.com/getpaseo/paseo/pull/9162) by [@fxlelouarn](https://github.com/fxlelouarn))
 - **Rebuilt mobile chat timeline:** The chat timeline on iOS and Android was rebuilt. Expanding or collapsing a turn summary, todo card or tool-call group keeps the line you tapped in place, and on Android so do Show more, Show less and plan cards. ([#8717](https://github.com/getpaseo/paseo/pull/8717), [#9085](https://github.com/getpaseo/paseo/pull/9085))
 - **Keyboard shortcuts on mobile:** With a keyboard connected, iPad and Android now run the same shortcuts as desktop, including your custom bindings. Shortcut hints and Settings → Shortcuts appear when a keyboard is detected. Shortcuts also work in narrow desktop and browser windows. ([#8625](https://github.com/getpaseo/paseo/pull/8625) by [@jeroenfrenken](https://github.com/jeroenfrenken), [@lstroud](https://github.com/lstroud))
 - **Touch-sized tablet controls:** On iPad and other touch-screen devices, the wide layout now has touch-sized buttons, rows and bars. The composer toolbar folds its controls into the model menu when space runs out, and swiping right on the workspace reveals a collapsed sidebar as an overlay. ([#8748](https://github.com/getpaseo/paseo/pull/8748), [#8885](https://github.com/getpaseo/paseo/pull/8885), [#8891](https://github.com/getpaseo/paseo/pull/8891), [#8909](https://github.com/getpaseo/paseo/pull/8909), [#9151](https://github.com/getpaseo/paseo/pull/9151), [#9238](https://github.com/getpaseo/paseo/pull/9238), [#8739](https://github.com/getpaseo/paseo/pull/8739) by [@zeyugao](https://github.com/zeyugao))
diff --git a/CHANGELOG.zh-CN.md b/CHANGELOG.zh-CN.md
index 792e79da3b..fd91d002ab 100644
--- a/CHANGELOG.zh-CN.md
+++ b/CHANGELOG.zh-CN.md
@@ -2,11 +2,11 @@
 
 ## 0.16.0-beta.1 - 2026-11-10
 
+- **后台任务**：Paseo 现在会在 Composer 上方显示 Agent 正在运行的后台任务，例如 shell 和监视器，每项都带“停止”按钮。支持 Claude Code、Codex 和 OpenCode v2。 ([#6220](https://github.com/getpaseo/paseo/pull/6220), [#9162](https://github.com/getpaseo/paseo/pull/9162)，贡献者：[@fxlelouarn](https://github.com/fxlelouarn))
 - **插件侧边栏视图**：插件可以用自己的布局替换侧边栏内容，展示所有已连接主机上的工作区、Agent、项目和终端。在“设置 → 侧边栏”中为每台设备选择视图；Paseo 的侧边栏页眉和页脚保持不变。 ([#8906](https://github.com/getpaseo/paseo/pull/8906))
 - **插件 Composer 控件**：插件可以向 Composer 添加自己的控件，并读取和设置其中的提示词、附件、Provider、模型、模式和思考强度。插件还可以把光标放到任意 Agent 的 Composer 中、向“新建工作区”添加条目，并在 Agent 和工作区上保存自己的元数据。 ([#8744](https://github.com/getpaseo/paseo/pull/8744), [#9209](https://github.com/getpaseo/paseo/pull/9209), [#9207](https://github.com/getpaseo/paseo/pull/9207))
 - **更快的 diff 加载**：打开“更改”时会立即显示文件树，文件内容随后加载。大型 diff 分批到达，加载期间应用的其他部分照常响应，并且 diff 优先于 daemon 的后台 worktree 扫描。 ([#8907](https://github.com/getpaseo/paseo/pull/8907), [#9241](https://github.com/getpaseo/paseo/pull/9241), [#9243](https://github.com/getpaseo/paseo/pull/9243))
 - **细节打磨**：一轮对话结束时聊天保持不动，返回没有变化的聊天时直接显示原样，无需刷新。工具行从第一帧起就显示最终标题和图标，上下文窗口浮层打开时用量已加载完成，侧边栏悬停卡片一次只打开一个。 ([#8944](https://github.com/getpaseo/paseo/pull/8944), [#9175](https://github.com/getpaseo/paseo/pull/9175), [#9242](https://github.com/getpaseo/paseo/pull/9242), [#9248](https://github.com/getpaseo/paseo/pull/9248), [#9212](https://github.com/getpaseo/paseo/pull/9212), [#9071](https://github.com/getpaseo/paseo/pull/9071))
-- **后台任务**：Paseo 现在会在 Composer 上方显示 Agent 正在运行的后台任务，例如 shell 和监视器，每项都带“停止”按钮。支持 Claude Code、Codex 和 OpenCode v2。 ([#6220](https://github.com/getpaseo/paseo/pull/6220), [#9162](https://github.com/getpaseo/paseo/pull/9162)，贡献者：[@fxlelouarn](https://github.com/fxlelouarn))
 - **重建移动端聊天时间线**：iOS 和 Android 上的聊天时间线已重建。展开或折叠轮次摘要、待办卡片或工具调用组时，你点按的那一行保持原位；在 Android 上，“显示更多”“收起”和计划卡片也是如此。 ([#8717](https://github.com/getpaseo/paseo/pull/8717), [#9085](https://github.com/getpaseo/paseo/pull/9085))
 - **移动端键盘快捷键**：连接键盘后，iPad 和 Android 现在可使用与桌面端相同的快捷键，包括你自定义的绑定。检测到键盘时会显示快捷键提示和“设置 → 快捷键”。在较窄的桌面端和浏览器窗口中快捷键同样可用。 ([#8625](https://github.com/getpaseo/paseo/pull/8625)，贡献者：[@jeroenfrenken](https://github.com/jeroenfrenken)、[@lstroud](https://github.com/lstroud))
 - **适合触控的平板控件**：在 iPad 和其他触屏设备上，宽屏布局现在使用适合触控尺寸的按钮、行和栏。Composer 工具栏在空间不足时会把控件收进模型菜单；在工作区上向右滑动，可将已折叠的侧边栏以浮层方式显示。 ([#8748](https://github.com/getpaseo/paseo/pull/8748), [#8885](https://github.com/getpaseo/paseo/pull/8885), [#8891](https://github.com/getpaseo/paseo/pull/8891), [#8909](https://github.com/getpaseo/paseo/pull/8909), [#9151](https://github.com/getpaseo/paseo/pull/9151), [#9238](https://github.com/getpaseo/paseo/pull/9238), [#8739](https://github.com/getpaseo/paseo/pull/8739)，贡献者：[@zeyugao](https://github.com/zeyugao))
diff --git a/docs/release.md b/docs/release.md
index 1b0ed36284..869aab78ec 100644
--- a/docs/release.md
+++ b/docs/release.md
@@ -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.