puter/paseo
1
0
Fork 0
mirror of https://github.com/getpaseo/paseo.git synced 2026-11-10 10:25:03 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat(changelog): lead each release with highlights and fold the rest away

Browse Source 
A release entry now opens with a short list of highlights above its first
section. The What's new sheet, the website changelog and the GitHub release
body show those and keep the sections, the full record, behind one control,
so a 100-bullet release reads as ten lines.

CHANGELOG.md stays plain Markdown because the app and the website render it
without HTML, including apps already installed. Each surface folds the
sections itself; only the release body gets a <details> block, written by
Release Notes Sync. A release with nothing before its first section shows
its sections as before.

Adds the 0.16.0-beta.1 entry in the new format, with its Chinese
translation, and the highlight writing rules in docs/release.md.
This commit is contained in:
Mohamed Boudra
2026-11-10 09:57:12 +01:00
parent 4c9c59ea2b
commit eda939b092
28 changed files with 852 additions and 97 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/release.md
+55 -4
View File
@@ -594,7 +594,7 @@ Release notes depend on the changelog heading format. The heading **must** be st
No prefix (`v`), no extra text. `Release Notes Sync` matches the `## X.Y.Z` (or `## X.Y.Z-beta.N`) line for the pushed tag to extract the version. A malformed heading breaks the release-notes sync for that tag.
`CHANGELOG.md` on `main` is also what the app's **What's new** sheet fetches and renders, so the file is a shipped product surface, not just a release input. `##` starts a release and `###` starts a section; the app reads section titles from the document, so renaming or adding one needs no app change. Everything under a section is rendered as Markdown: prose, lists, links, inline code, fenced code, block quotes, tables, and images. Raw HTML does not render — the shared Markdown parser runs with `html: false`, so a `<video>`, `<iframe>` or `<embed>` tag reaches the reader as visible markup. Keep media out of the changelog, or link to it. A GitHub callout renders as a block quote with its `[!NOTE]` marker still in the text. A release entry is what a user reads on a phone the moment they are offered the update — write it for them.
`CHANGELOG.md` on `main` is also what the app's **What's new** sheet fetches and renders, so the file is a shipped product surface, not just a release input. `##` starts a release and `###` starts a section; the app reads section titles from the document, so renaming or adding one needs no app change. Content between the release heading and the first `###` is the release's [highlights](#changelog-highlights). The What's new sheet, the website changelog and the GitHub release body show the highlights and keep the sections collapsed behind one control: Show all changes in the app and on the website, and an All changes `<details>` block that `Release Notes Sync` writes into the release body, so the file itself never needs HTML. A release with nothing before its first `###` shows its sections. Older entries that open with summary paragraphs are treated as highlights. Everything under a section is rendered as Markdown: prose, lists, links, inline code, fenced code, block quotes, tables, and images. Raw HTML does not render — the shared Markdown parser runs with `html: false`, so a `<video>`, `<iframe>` or `<embed>` tag reaches the reader as visible markup. Keep media out of the changelog, or link to it. A GitHub callout renders as a block quote with its `[!NOTE]` marker still in the text. A release entry is what a user reads on a phone the moment they are offered the update — write it for them.
## Changelog policy
@@ -613,7 +613,7 @@ Older prerelease bodies on GitHub keep the notes they were synced with; `Release
- The release agent writes the Chinese entry in the changelog commit, after the English entry is approved. Every beta that rewrites the English entry rewrites the Chinese one too, and promotion renames both. `packages/website/e2e/i18n.spec.ts` fails CI on the release commit when any entry has no current translation.
- A translated entry uses the English heading unchanged: `## X.Y.Z - YYYY-MM-DD`. The website uses it only while the version and date both match the English entry. Otherwise it shows that release whole in English under a notice. Delete Chinese entries whose English entry was renamed.
- Keep the English sections, bullets and links one to one. Section titles: Added 新增, Improved 改进, Changed 变更, Fixed 修复, Security 安全, Breaking 破坏性变更, Plugins 插件, Notes 说明. Wording follows [website-i18n.md](website-i18n.md#chinese-style).
- Keep the English highlights, sections, bullets and links one to one. Section titles: Added 新增, Improved 改进, Changed 变更, Fixed 修复, Security 安全, Breaking 破坏性变更, Plugins 插件, Notes 说明. Wording follows [website-i18n.md](website-i18n.md#chinese-style).
## Changelog ownership
@@ -656,7 +656,7 @@ claims a general improvement, rewrite it with the concrete change.
## Changelog conciseness
Every bullet must be scannable at a glance. The changelog is not release documentation — it's a list.
Every section bullet must be scannable at a glance. The changelog is not release documentation — it's a list. [Highlights](#changelog-highlights) get more room; every other bullet follows these limits.
- **One sentence per bullet, max.** If a bullet contains two sentences, the second one is doing work that belongs in product docs, not the changelog. Cut it.
- **No trailing periods.** Bullets are list items, not prose. Drop the period at the end of every bullet, including the period inside any bolded lead-in. `**Configurable terminal scrollback**` not `**Configurable terminal scrollback.**`.
@@ -666,6 +666,57 @@ Every bullet must be scannable at a glance. The changelog is not release documen
- **Stop after identifying the change.** Do not explain LAN/WAN topology, TLS handshakes, IPC, or other architecture in a changelog bullet. Put necessary background in product docs.
- **Attribution follows the split.** When you split a dense bullet, move each PR/author to the bullet it belongs to. Never duplicate the same PR across multiple bullets.
## 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.
```markdown
## 0.16.0 - 2026-11-20
- **Undo workspace archive:** Archiving a workspace in the app now shows a "Workspace archived" toast for six seconds. Undo, or Cmd/Ctrl+Z, restores the workspace with its tabs and agents. ([#8904](https://github.com/getpaseo/paseo/pull/8904))
### Added
```
- **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.
- **The lead-in is not a place or something Paseo already had.** A device, screen or area names
where the change landed. A feature name that was true of the last release hides the news: Paseo
already had keyboard shortcuts, so the lead-in says they now work on mobile.
- **The first sentence says the plain thing.** Write what a user would tell a friend: Paseo now
shows the background tasks an agent is running. Leave out the conditions and mechanics that make
it true.
- **Describe the new behavior, not the old one.** Say what is faster or better now, and do not
dwell on how slow or broken it was before. A number is welcome as a short aside after the new
behavior is stated: seconds, a percentage, a multiple.
- **Do not list what a sentence already covers.** After "the same shortcuts as desktop", naming
five of them adds nothing. Keep a list only when it sets the scope, such as the providers a
feature works with.
- **The description runs one to three sentences.** Sentences end with periods, and the attribution
follows the last one. [Changelog wording](#changelog-wording) applies in full.
- **A highlight replaces the section bullets it covers.** A PR appears once in an entry, so its
attribution moves to the highlight.
- **A highlight is something a user would name.** Everything else stays a section bullet. A patch
release still has one: the change it ships for.
- **Fixes are routine and stay in `### Fixed`.** Do not add a summary of fixes. A fix, or a group
of related fixes, becomes a highlight only when it passes the same test as a feature, and then
it is written as what works now: `**Fewer reconnects on return:**`.
| Avoid | Write |
| ------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
| `**iPad and touch screens:**` | `**Touch-sized tablet controls:**` |
| `**Hardware keyboard shortcuts:**` | `**Keyboard shortcuts on mobile:**` |
| When an agent ends its turn while shells it started are still running, a pill lists them | Paseo now shows the background tasks an agent is running |
| A diff no longer waits 4 to 40 seconds behind worktree scans | Opening Changes shows the file tree right away, and diffs load about 6 times sooner on hosts with many worktrees |
| 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.
## Changelog attribution
Every changelog bullet must credit contributors and link to the PR(s) that delivered the change. This is not one-PR-per-line — a single bullet describes a user-facing change and may reference multiple PRs.
@@ -697,7 +748,7 @@ Rules:
## Changelog ordering
Entries within each section (Added, Improved, Fixed) are ordered by user impact:
Highlights come first, ordered by user impact. Entries within each section (Added, Improved, Fixed) follow the same 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.