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

docs: add changelog authoring guidance

Browse Source 
Adds a dedicated skill for drafting user-facing unreleased changelog entries.
Covers both the main app changelog and the VS Code extension changelog.
Updates agent guidance to route changelog work to the new skill.
This commit is contained in:
Bohdan Triapitsyn
2026-08-12 01:23:57 +03:00
parent b8df186822
commit d1224213ca
3 changed files with 108 additions and 58 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.agents/skills/changelog-authoring/SKILL.md
+107
View File
@@ -0,0 +1,107 @@
---
name: changelog-authoring
description: Use when drafting or updating user-facing CHANGELOG.md entries for the OpenChamber `[Unreleased]` section, including the VS Code extension changelog, summarizing changes since the latest git tag.
license: MIT
compatibility: opencode
---
## Overview
Draft user-facing bullet points for the `## [Unreleased]` section that summarize changes since the latest git tag up to `HEAD`.
Two files are maintained:
- `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.
## Gather Context First
Read recent release sections for style before drafting:
```bash
head -140 CHANGELOG.md
```
Collect git context (base tag, commit count, changed files):
```bash
BASE=$(git describe --tags --abbrev=0 2>/dev/null || git rev-list --max-parents=0 HEAD)
echo "Base: $BASE"
echo "Commits since base: $(git rev-list --count "$BASE"..HEAD)"
echo "Diff stats: $(git diff --shortstat "$BASE"..HEAD)"
echo "=== Top 30 commits ==="; git log --oneline -30 "$BASE"..HEAD
echo "=== Changed files ==="; git diff --stat "$BASE"..HEAD
```
Inspect all commits after the base up to `HEAD`. Use the changed files/code paths to decide which platform each change touches.
## Squashed PR Merges
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.
```bash
# Find PR-linked commits since base
BASE=$(git describe --tags --abbrev=0 2>/dev/null || git rev-list --max-parents=0 HEAD)
git log --oneline "$BASE"..HEAD | grep -oE '#[0-9]+'
# Read a PR's title, body, and author (requires gh)
gh pr view <number> --json number,title,body,author,mergedAt
```
- 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.
## Writing Style
- 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."
## Highlights and Ordering
- 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.
- 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.
## VS Code Changelog Rules
- Craft entries only for behavior present in the VS Code extension. Exclude Desktop, Web, Mobile/PWA, and main-app-only UI.
- 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.
## 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).
## Quality Checks Before Editing
- 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.
## Workflow
1. Gather repo style and git context (commands above).
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.
.opencode/commands/changelog.md
-58
View File
@@ -1,58 +0,0 @@
---
description: Draft user-facing CHANGELOG.md entries for [Unreleased]
agent: build
---
You are updating @CHANGELOG.md and @packages/vscode/CHANGELOG.md.
Goal: write user-facing bullet points for the `## [Unreleased]` section that summarize the changes since the latest git tag up to `HEAD`.
Style rules:
- Match the writing style of the existing changelog (tone + level of detail).
- Write like release notes for actual users, not a marketing summary. Be concrete and plain-spoken.
- Avoid generic payoff clauses like "making X faster", "improving reliability", "for a smoother workflow", or "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 consequence if it is obvious.
- Avoid internal implementation details, but do not replace them with vague benefits. If a technical change has no clear user-visible effect, omit it or group it under a plain reliability bullet.
- Avoid internal component names unless users see them (ex: "VS Code extension", "Desktop app", "Web app").
- For @packages/vscode/CHANGELOG.md: Craft entries specifically for behavior that is present in the VS Code extension. Exclude Desktop app, Web app, Mobile/PWA, and main-app-only UI. Do not copy shared/main changelog bullets into this file 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.
- Prefer grouping by platform only if it reads better.
- No new release header; only update the `[Unreleased]` bullets.
- Don't include implementation notes, commit hashes, or file paths in the changelog text.
- Use area prefixes when helpful for grouping in the main @CHANGELOG.md (e.g., "Chat:", "VSCode:", "Settings:", "Git:", "Terminal:", "Mobile:", "UI:").
- Credit contributors inline using "(thanks to @username)" at the end of the bullet. Find contributor usernames from commit authors (not email, but a github username) or PR metadata when available. Skip if contributor is btriapitsyn, since this is a repo owner.
Highlights and ordering:
- Review several recent release sections before drafting. Match how they reserve bold area prefixes for release highlights and order the remaining bullets by user importance.
- Sort bullets by user impact, not commit order. Put breaking changes first, then the most significant new capabilities or broad user-visible improvements, followed by smaller features, fixes, and visual polish.
- Mark only the strongest release highlights with a bold area prefix, such as `- **Chat attachments:** ...`. Usually this is the first 1-3 bullets, but use fewer when the release does not contain enough substantial changes and more only when clearly justified.
- Treat a change as a highlight when it introduces a substantial user-facing capability, materially changes a common workflow, or fixes a severe/widespread user-facing problem. Do not bold a bullet merely because it is first, has a large diff, or was difficult to implement.
- Keep related platform bullets together only when that does not push a more important change too far down the list.
- Rank highlights independently in the main and VS Code changelogs. A main-app highlight is not automatically a VS Code highlight, and the extension may have different top changes.
Quality checks before editing:
- For every bullet, ask: "Could a user point to this in the UI or behavior?" If not, rewrite it or drop it.
- For every VS Code bullet, verify the change applies to the extension, not just shared web UI or server code. When unsure, leave it out of @packages/vscode/CHANGELOG.md.
- For every bold bullet, ask: "Would a user reasonably describe this as one of the release's headline changes?" If not, remove the bold styling or move it lower.
- Read the finished list top to bottom and confirm that each bullet is no more important than the bullets above it, except where keeping closely related platform bullets together improves readability.
- Do not mention low-level mechanics such as "local refs first", "source of truth", "route", "store", "cache", "payload", or "ref resolution". Translate only when there is a clear user-facing symptom.
- Do not bundle unrelated changes just to reduce bullet count. It is better to omit minor internal fixes than to create a vague catch-all sentence.
- Avoid LinkedIn-style language. Bad: "commit review is faster and branch history is more reliable." Better: "commit history can now show file diffs inline." Bad: "installed-state accuracy is improved." Better: "the skills list now matches OpenCode's installed skills more closely."
Determine the base version:
- Use the latest tag (ex: `v1.3.2`) as the base.
- Inspect all commits after the base up to `HEAD`.
Repo context for style:
!`head -140 CHANGELOG.md`
Git context (base tag, commits, changed files):
!`BASE=$(git describe --tags --abbrev=0 2>/dev/null || git rev-list --max-parents=0 HEAD); echo "Base: $BASE"; echo "Commits since base: $(git rev-list --count "$BASE"..HEAD)"; echo "Diff stats: $(git diff --shortstat "$BASE"..HEAD)"; echo; echo "=== Top 30 commits ==="; git log --oneline -30 "$BASE"..HEAD; echo; echo "=== Changed files ==="; git diff --stat "$BASE"..HEAD`
Additional hints (optional, use only if needed):
- If there are breaking changes or user-visible behavior changes, call them out first.
- If changes are mostly internal refactors, mention them only when there is a concrete user-visible fix. Otherwise do not add a changelog bullet for them.
Now:
1) Propose the new `[Unreleased]` bullet list for the main @CHANGELOG.md.
2) Propose the VS Code-specific `[Unreleased]` list for @packages/vscode/CHANGELOG.md.
3) Edit both files to update their respective `[Unreleased]` sections.
AGENTS.md
+1
View File
@@ -93,6 +93,7 @@ process violation.
| Settings UI, settings dialogs, configuration surfaces, or settings search | `settings-ui-patterns` |
| Sortable or drag-to-reorder behavior, especially `@dnd-kit` and touch/wrapping layouts | `drag-to-reorder` |
| iOS Simulator build, launch, preview, gestures, or `serve-sim` control | `serve-sim` |
| Drafting or updating user-facing CHANGELOG entries for the `[Unreleased]` section (main app or VS Code extension) | `changelog-authoring` |
Pure code-reading or explanation does not require implementation skills unless needed to interpret a specialized subsystem.