BuzzbeeSCD/openchamber
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(changelog): title every release and require one

Browse Source 
Every release file now carries a title: two to six plain words naming the
change a user would remember it for. The generator refuses a release without
one, promote carries the title from unreleased.md, and the unreleased
template opens with a title line. The changelog-authoring skill and the
format README describe how to write it.

Claude-Session: https://claude.ai/code/session_01VqV56Hez25hTxXH4ipJfzH
This commit is contained in:
Bohdan Triapitsyn
2026-09-05 16:45:29 +03:00
parent 475dc5ecb1
commit a1bc1368ae
144 changed files with 325 additions and 154 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.agents/skills/changelog-authoring/SKILL.md
+21 -1
View File
@@ -11,7 +11,7 @@ The changelog is written once per release, by the maintainer, as one story. Both
Write `changelog/unreleased.md` and nothing else. `CHANGELOG.md`, `packages/vscode/CHANGELOG.md`, and `changelog/index.json` are generated from `changelog/*.md`; after editing run `bun run changelog:build` and commit the source with the regenerated files (`changelog/README.md` describes the file format, `bun run changelog:check` verifies the outputs). The version header, date, and file promotion happen at release time through `oc-dev create-release`, never by hand.
`unreleased.md` holds two sections:
`unreleased.md` opens with a `title:` front matter line (see The title) and holds two sections:
- `## App` — Web, Desktop, Mobile/PWA, shared UI.
- `## VS Code` — the extension only, written separately (see below).
@@ -44,6 +44,25 @@ Where a change goes:
The generator emits the groups in this order whatever order the source lists them, drops empty ones, and writes the `## [x.y.z] - YYYY-MM-DD` header that the update dialog, the release workflow, and the website match by regex.
## The title
Every release carries a one-line `title:` in its front matter. The website lists it beside the version and uses it as the heading of the release page, so it is the one line most people read. It answers "what would a user remember this release for":
- **Two to six words** naming the change most users will notice. For a fix-only patch, name what works again: `Terminal works again on Windows`, `Faster session switching`.
- **Plain words, sentence case**; product names keep their casing. No area prefix with a colon, no trailing period, no version number, no credit.
- **Never a category alone** (`Fixes`, `Stability`, `Improvements`, `Polish`) and **never a bare area** (`Git`, `Chat`): the title has to teach the reader something.
- Two headliners at most, joined with `and`, and only when the release really has two.
The generator refuses a release without a title. In `unreleased.md` it sits at the top:
```markdown
---
title: Comments on code in VS Code
---
## App
```
## 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:
@@ -106,4 +125,5 @@ Read each finished section top to bottom and check every bullet:
- Empty groups are absent; present groups appear in the order New, Improvements, Fixes, Misc.
- It appears only in the section whose runtime receives it.
- Its contributor is credited.
- The `title:` line names the release's headline change in two to six plain words.
- `bun run changelog:build` ran and the regenerated files are staged with the source.