docs(changelog): group release notes and rewrite the authoring skill
Release sections now carry New, Improvements, Fixes, and Misc groups, and the bullets are written for a user who never opened the code: one or two plain sentences naming what they see. The changelog-authoring skill makes that shape the primary rule, with a worked example, a five-second reader test, and checks per bullet. Claude-Session: https://claude.ai/code/session_01VqV56Hez25hTxXH4ipJfzH
This commit is contained in:
Bohdan Triapitsyn
@@ -5,22 +5,67 @@ license: MIT
|
||||
compatibility: opencode
|
||||
---
|
||||
|
||||
## Overview
|
||||
## Gate
|
||||
|
||||
**Gate: an explicit maintainer request.** The changelog is written once per release, by the maintainer, as a single story. Both `CHANGELOG.md` files stay untouched by fixes, features, PR merges, de-slop follow-ups, and every other task — a change lands without a changelog line, and the maintainer folds it in later. Proceed past this point only when the current message asks to update the changelog; otherwise stop and leave both files as they are.
|
||||
The changelog is written once per release, by the maintainer, as one story. Both `CHANGELOG.md` files stay untouched by every other task; a fix or a merged PR lands without a changelog line. Proceed only when the current message asks to update the changelog.
|
||||
|
||||
Draft user-facing bullet points for the `## [Unreleased]` section that summarize changes since the latest git tag up to `HEAD`.
|
||||
|
||||
Two files are maintained:
|
||||
Two files, `[Unreleased]` content only, never a new release header:
|
||||
|
||||
- `CHANGELOG.md` — main app (Web, Desktop, Mobile/PWA, shared UI).
|
||||
- `packages/vscode/CHANGELOG.md` — VS Code extension only.
|
||||
|
||||
Only update the `[Unreleased]` bullets. Never add a new release header.
|
||||
## The shape of a release
|
||||
|
||||
## Gather Context First
|
||||
Every release section is grouped. Under the version header come, in this order and only when non-empty:
|
||||
|
||||
Read recent release sections for style. Determine the latest tag (or initial commit fallback), then inspect every commit and changed path through `HEAD`:
|
||||
```markdown
|
||||
### New
|
||||
- **VS Code: comments on code.** Select lines, click the `+` in the gutter ... (thanks to @felipegenef)
|
||||
- Project actions in worktrees: a session in a worktree can use the parent project's saved actions (thanks to @mattv8).
|
||||
|
||||
### Improvements
|
||||
- Chat: Markdown tables are readable again, columns take the width their content needs (thanks to @ChangeHow).
|
||||
|
||||
### Fixes
|
||||
- Chat: huge patches in tool cards open without freezing the page (thanks to @karimodm).
|
||||
|
||||
### Misc
|
||||
- Bundled OpenCode updated to 1.19.
|
||||
```
|
||||
|
||||
Where a change goes:
|
||||
|
||||
- **New** — something the user could not do before: a feature, a surface, a language.
|
||||
- **Improvements** — something they could do works better or reads clearer now.
|
||||
- **Fixes** — something was broken and showed a wrong result; the bullet names the symptom.
|
||||
- **Misc** — bundled tool versions, packaging, platform support, retirements. Rarely more than a few lines.
|
||||
|
||||
The `## [x.y.z] - YYYY-MM-DD` header line stays exactly that; the app's update dialog, the release workflow, and the release script match it by regex. The `###` group headings inside it render on GitHub and in the app, and the website flattens them to bullets until it learns to group.
|
||||
|
||||
## The bullet
|
||||
|
||||
The reader is a user of the app. They never opened the code, they will not open the PR, and they give a bullet about five seconds. Write for that reader:
|
||||
|
||||
- **One sentence, two at most.** A bold highlight may take three. Under about 200 characters for a regular bullet.
|
||||
- **Name what they see or do.** The screen, the button, the gesture, the outcome. When a fix removed a symptom, name the symptom in plain words ("froze the page", "sent the comment by accident", "stopped at the first page").
|
||||
- **Plain words only.** Anything a user would have to look up is out: store, cache, route, payload, reconcile, authoritative, lifecycle, runtime, listing, revision, PTY, bridge. Internal component names are out unless the user sees them on screen.
|
||||
- **State the new behaviour directly.** Say what happens now. Framing it against the old way ("X, not Y", "instead of Y", "rather than Y") is the tell of machine-written notes; drop the second half and let the sentence stand.
|
||||
- **Area prefix, then the fact.** `Chat:`, `Settings/Providers:`, `Git:`, `Mobile:`, `Server:`, `CLI:`, `VS Code:` in the main file. A highlight bolds its prefix: `- **Project actions:** ...`.
|
||||
- **Details stay in the PR.** No commit hashes, file paths, numbers that do not change what the user does, or mechanism. One concrete number is fine when it is the whole point ("more than 200 sessions").
|
||||
|
||||
Worked example, same change:
|
||||
|
||||
> Weak: *a saved action counts as running exactly while its command runs. When the command exits, the stop icon goes away even if the terminal tab stays open, and a second client can start the action again. Every client shows the same run, and the sidebar marks a directory that has one. Sessions in a linked worktree can use the parent project's actions; they run in the worktree by default.*
|
||||
>
|
||||
> Good: *the running state of a saved action is reliable now. It shows as running only while the command is really running, every device sees the same state, and the sidebar shows which project has something running. Worktrees can use the parent project's actions.*
|
||||
|
||||
The weak version is accurate and lost the reader at the first comma. The good version keeps the three things a user notices and drops the mechanics that explain them.
|
||||
|
||||
Load `.agents/skills/communication-style/SKILL.md` and run its pattern scan over the finished lists; its rules on em dashes, hedging, and puffery apply here unchanged.
|
||||
|
||||
## Gather
|
||||
|
||||
Determine the base and read everything through `HEAD`:
|
||||
|
||||
```bash
|
||||
BASE=$(git describe --tags --abbrev=0 2>/dev/null || git rev-list --max-parents=0 HEAD)
|
||||
@@ -28,70 +73,34 @@ git log --oneline "$BASE"..HEAD
|
||||
git diff --stat "$BASE"..HEAD
|
||||
```
|
||||
|
||||
Context gathering is complete when each user-visible change has evidence, platform reach, and contributor identity where available.
|
||||
A squashed merge (subject ending in `(#123)`) or a `Merge pull request #123` commit hides the real change behind a terse subject. Read the PR: `gh pr view <number> --json number,title,body,author,mergedAt`. Distill its intent into the bullet shape above; the body's own wording is reviewer-facing and stays there. When `gh` cannot fetch it, use the commit and diff and say what remains uncertain.
|
||||
|
||||
## Squashed PR Merges
|
||||
**Follow-ups fold in.** A maintainer commit that completes or reworks a merged PR (a "complete ... follow-ups" commit, a reshaping merge) has no bullet of its own; its user-visible effect goes into the bullet of the PR it finished, written as one behaviour. A change with no user-visible effect (tooling, CI, tests, docs, dead-code removal, internal guards) gets no bullet at all.
|
||||
|
||||
A squashed merge commit often collapses a whole PR into a single terse subject line that omits valuable detail. When a commit looks like a squashed PR merge (subject ending in `(#123)`, or a `Merge pull request #123` commit), inspect the PR itself — its title and description usually carry the real user-facing context.
|
||||
Gathering is complete when every user-visible change has evidence, a known platform reach, and a contributor identity where one exists.
|
||||
|
||||
Use `gh pr view <number> --json number,title,body,author,mergedAt` for PR evidence.
|
||||
## Order and highlights
|
||||
|
||||
- Prefer the PR description over the squashed commit subject when the description explains the user-visible change more accurately.
|
||||
- Do not copy PR descriptions verbatim; distill them into the changelog style below.
|
||||
- Use PR author/metadata to attribute contributor credit (see Contributor Credit).
|
||||
- If `gh` is unavailable or the PR cannot be fetched, fall back to the commit message and diff, and note any uncertainty rather than inventing details.
|
||||
- Inside each group, sort by user impact: breaking changes, then what most users meet daily, then the rest, visual polish last.
|
||||
- Bold the prefix of the strongest one to three bullets in the whole release and put each at the top of its group. A highlight introduces a capability, changes a common workflow, or fixes something severe. Size of the diff and effort spent are not reasons to bold.
|
||||
- A change that is both a feature and a fix (a reworked area) gets one bullet in the group that describes what the user gains most; a second bullet only when the two halves are things a user would look for separately.
|
||||
- Rank each changelog on its own; a main-app highlight is not automatically a VS Code highlight.
|
||||
|
||||
## Writing Style
|
||||
## VS Code changelog
|
||||
|
||||
- Match the tone and level of detail of the existing changelog.
|
||||
- Write like release notes for real users, not marketing. Be concrete and plain-spoken.
|
||||
- Avoid generic payoff clauses ("making X faster", "improving reliability", "for a smoother workflow", "so you can...") unless the diff clearly proves that exact user-visible outcome.
|
||||
- Prefer short direct bullets: what changed, where users see it, and only one obvious consequence.
|
||||
- Omit internal implementation details; do not replace them with vague benefits. If a technical change has no user-visible effect, omit it or group under a plain reliability bullet.
|
||||
- Avoid internal component names unless users see them (ex: "VS Code extension", "Desktop app", "Web app").
|
||||
- Use area prefixes in the main changelog when they help grouping (e.g., "Chat:", "VSCode:", "Settings:", "Git:", "Terminal:", "Mobile:", "UI:").
|
||||
- Do not include commit hashes, file paths, or implementation notes in changelog text.
|
||||
- Do not mention low-level mechanics ("local refs first", "source of truth", "route", "store", "cache", "payload", "ref resolution"). Translate only when there is a clear user-facing symptom.
|
||||
- Avoid LinkedIn-style language. Bad: "commit review is faster and branch history is more reliable." Better: "commit history can now show file diffs inline."
|
||||
An entry belongs here only when the extension actually mounts the surface: trace from `packages/vscode/webview/main.tsx` → `VSCodeApp` → `VSCodeLayout`, which mounts a subset of the shared UI, and read the surface map in `packages/vscode/src/DOCUMENTATION.md`. Server-side changes have no entry here; the extension runs no OpenChamber server. Prefixes drop the `VS Code:` part. When reachability is uncertain, leave the entry out; a false entry becomes a bug report.
|
||||
|
||||
## Highlights and Ordering
|
||||
## Credit
|
||||
|
||||
- Sort bullets by user impact, not commit order. Breaking changes first, then significant new capabilities or broad user-visible improvements, then smaller features, fixes, and visual polish.
|
||||
- Keep the opening highlight block contiguous. Place every bold highlight before the first regular bullet; a regular bullet marks the end of the highlight block.
|
||||
- Mark only the strongest highlights with a bold area prefix, such as `- **Chat attachments:** ...`. Usually the first 1–3 bullets; fewer when the release lacks substantial changes, more only when clearly justified.
|
||||
- Treat a change as a highlight only when it introduces a substantial user-facing capability, materially changes a common workflow, or fixes a severe/widespread problem. Do not bold merely because a bullet is first, has a large diff, or was hard to implement.
|
||||
- Keep related platform bullets together only when that does not push a more important change too far down.
|
||||
- Rank highlights independently in each changelog. A main-app highlight is not automatically a VS Code highlight.
|
||||
End the bullet with `(thanks to @username)` using the GitHub login from the PR or commit. The repo owner `btriapitsyn` gets no credit line.
|
||||
|
||||
## VS Code Changelog Rules
|
||||
## Done when
|
||||
|
||||
- Craft entries only for behavior present in the VS Code extension. Exclude Desktop, Web, Mobile/PWA, and main-app-only UI.
|
||||
- **Reachability check before every entry.** A change touching shared UI or the VS Code bridge earns a VS Code changelog entry only when the surface is actually mounted from the VS Code entrypoint (`packages/vscode/webview/main.tsx` → `VSCodeApp` → `VSCodeLayout` — which mounts only a subset of shared surfaces; consult the surface map in `packages/vscode/src/DOCUMENTATION.md` when present, trace the mount when not). Shared code that VS Code never mounts is dead there — an entry for it is a false claim users will file bugs about. When in doubt, leave the entry out of the VS Code changelog.
|
||||
- Do not copy shared/main bullets here unless changed files or code paths show the feature exists in the extension.
|
||||
- Focus on core UI improvements and VS Code integration.
|
||||
- Do NOT use "VSCode:" or "VS Code:" prefixes in this file.
|
||||
- When unsure whether a change reaches the extension, leave it out.
|
||||
Read each finished list top to bottom and check every bullet:
|
||||
|
||||
## Contributor Credit
|
||||
|
||||
- Credit contributors inline with "(thanks to @username)" at the end of the bullet.
|
||||
- Find usernames from commit authors (GitHub username, not email) or PR metadata when available.
|
||||
- Skip credit when the contributor is `btriapitsyn` (repo owner).
|
||||
|
||||
## Completion Criteria
|
||||
|
||||
- For every bullet: "Could a user point to this in the UI or behavior?" If not, rewrite or drop it.
|
||||
- For every VS Code bullet: verify the change applies to the extension, not just shared web UI or server code.
|
||||
- For every bold bullet: "Would a user reasonably call this a headline change?" If not, unbold or move it lower.
|
||||
- Read the finished list top to bottom; confirm each bullet is no more important than those above it, except where keeping related platform bullets together improves readability.
|
||||
- Do not bundle unrelated changes to reduce bullet count. Prefer omitting minor internal fixes over vague catch-all sentences.
|
||||
- Mention mostly-internal refactors only when there is a concrete user-visible fix; otherwise add no bullet.
|
||||
|
||||
The lists are complete when every bullet is supported by inspected evidence, points to user-observable behavior, is ranked by impact, appears only in changelogs whose runtime receives it, and credits eligible contributors.
|
||||
|
||||
## Workflow
|
||||
|
||||
1. Gather repo style and complete git/PR context.
|
||||
2. Propose the new `[Unreleased]` bullet list for the main `CHANGELOG.md`.
|
||||
3. Propose the VS Code-specific `[Unreleased]` list for `packages/vscode/CHANGELOG.md`.
|
||||
4. Edit both files to update their respective `[Unreleased]` sections.
|
||||
- A user could point at it in the app within five seconds of reading it.
|
||||
- It is one or two sentences (three for a highlight) in plain words, with no mechanism and no contrast against the old behaviour.
|
||||
- It sits in the group its wording claims (a Fix names a symptom, a New names a capability) and no higher than the bullets above it in impact.
|
||||
- Empty groups are absent; present groups appear in the order New, Improvements, Fixes, Misc.
|
||||
- It appears only in the changelog whose runtime receives it.
|
||||
- Its contributor is credited.
|
||||
|
||||
@@ -4,6 +4,33 @@ All notable changes to this project will be documented in this file.
|
||||
|
||||
## [Unreleased]
|
||||
|
||||
### New
|
||||
|
||||
- **VS Code: comments on code.** Select lines, click the `+` in the gutter or right-click → OpenChamber → Add Comment, and write your note. It stays pinned to the code and goes out with your next message as a context card. Works in diffs too (thanks to @felipegenef).
|
||||
- Project actions in worktrees: a session in a worktree can use the parent project's saved actions (thanks to @mattv8).
|
||||
- VS Code: the extension is available in Turkish (thanks to @fitzgpt).
|
||||
|
||||
### Improvements
|
||||
|
||||
- **Project actions:** the running state of a saved action is reliable now. It shows as running only while the command is really running, every device sees the same state, and the sidebar shows which project has something running (thanks to @mattv8).
|
||||
- Chat: Markdown tables are readable again, columns take the width their content needs (thanks to @ChangeHow).
|
||||
- Mobile: with a draft typed, the collapsed composer always has a send button. While the agent is working, that button queues the message (thanks to @ChangeHow).
|
||||
- Server: OpenCode config paths respect `XDG_CONFIG_HOME` (thanks to @travisdoherty).
|
||||
- VS Code: a fresh install uses VS Code's language until you choose one in Settings.
|
||||
|
||||
### Fixes
|
||||
|
||||
- **Settings/Providers:** editing a custom provider keeps all of its model settings, and VS Code saves the protocol you chose (thanks to @hehuaiyu).
|
||||
- Chat: huge patches in tool cards open without freezing the page (thanks to @karimodm).
|
||||
- Chat: pressing Enter to confirm text on a Japanese, Chinese, or Korean keyboard no longer sends a comment by accident (thanks to @ChangeHow).
|
||||
- Chat: a queued slash command with attached context is delivered correctly, and the "Queued messages" card disappears after the last message goes out.
|
||||
- Goal Mode: when a reply is cut off by the length limit, the goal continues, and Resume gives it another try (thanks to @bashrusakh).
|
||||
- Sessions: subagent sessions are found in projects with more than 200 sessions (thanks to @bashrusakh).
|
||||
- Server: the terminal works in the Docker image, and non-Latin text renders correctly there (thanks to @yulia-ivashko).
|
||||
- CLI: on Windows, `openchamber` starts the server under Bun when Bun is installed.
|
||||
- VS Code: on Windows, the status command and adding a folder to the workspace handle drive-letter case correctly (thanks to @pttydou).
|
||||
- VS Code: permission auto-accept works again with the stable OpenCode (thanks to @bashrusakh).
|
||||
|
||||
## [1.22.1] - 2026-09-04
|
||||
|
||||
- **OpenCode Go:** every request OpenChamber sends to OpenCode Go on its own, such as commit messages and pull request text, reply recaps and suggested follow-ups, walkthroughs, Goal Mode checks, notes, and usage, now carries the `x-opencode-session` header that OpenCode Go requires from 6 September. Chat traffic already had it, because it goes through OpenCode. Update before that date if you use OpenCode Go.
|
||||
|
||||
@@ -1,3 +1,25 @@
|
||||
## [Unreleased]
|
||||
|
||||
### New
|
||||
|
||||
- **Comments on code.** Select lines, click the `+` in the gutter or right-click → OpenChamber → Add Comment, and write your note. It stays pinned to the code and goes out with your next message as a context card. Works in diffs too (thanks to @felipegenef).
|
||||
- The extension is available in Turkish (thanks to @fitzgpt).
|
||||
|
||||
### Improvements
|
||||
|
||||
- Chat: Markdown tables are readable again, columns take the width their content needs (thanks to @ChangeHow).
|
||||
- OpenCode config paths respect `XDG_CONFIG_HOME`.
|
||||
- A fresh install uses VS Code's language until you choose one in Settings.
|
||||
|
||||
### Fixes
|
||||
|
||||
- Settings/Providers: editing a custom provider keeps all of its model settings and saves the protocol you chose (thanks to @hehuaiyu).
|
||||
- Chat: huge patches in tool cards open without freezing the view (thanks to @karimodm).
|
||||
- Chat: pressing Enter to confirm text on a Japanese, Chinese, or Korean keyboard no longer sends a comment by accident (thanks to @ChangeHow).
|
||||
- Sessions: subagent sessions are found in projects with more than 200 sessions (thanks to @bashrusakh).
|
||||
- Permission auto-accept works again with the stable OpenCode (thanks to @bashrusakh).
|
||||
- On Windows, the status command and adding a folder to the workspace handle drive-letter case correctly (thanks to @pttydou).
|
||||
|
||||
## [1.22.1] - 2026-09-04
|
||||
|
||||
- **OpenCode Go:** the usage request the extension sends to OpenCode Go now carries the `x-opencode-session` header that OpenCode Go requires from 6 September. Chat traffic already had it, because it goes through OpenCode.
|
||||
|
||||
Reference in New Issue
Block a user