document-feature · diff
git:20260602.0c92335 to git:20260730.f8391d4
53 added, 12 removed. Audit A to A.
---
name: document-feature
- description: Use when a new feature, improvement, or breaking change has been implemented. Adds an entry to docs/releases/ so it appears in the in-product admin changelog.
+ description: Use when a new feature, improvement, bug fix, or breaking change has been implemented. Adds an entry to docs/releases/ so it appears in the in-product admin changelog.
user-invocable: true
---
# Release Documentation
- When a feature, improvement, or breaking change is implemented, add an entry to the appropriate
- Markdown file under `docs/releases/`.
+ When a feature, improvement, bug fix, or breaking change is implemented, add an entry to the
+ appropriate Markdown file under `docs/releases/`.
## Determining the Version
Read the current version from `server/package.json` → `version` field.
If the version contains a build suffix (e.g. `fix-issue-1137-lVuXg`) look for the nearest clean
semver tag in the git log: `git tag --sort=-version:refname | head -5`.
Use the highest existing `docs/releases/` subdirectory name as a fallback.
## Directory Structure
```
docs/releases/{version}/
features.md New capabilities (admin-facing and end-user-facing)
+ fixes.md Corrections to behaviour that was already supposed to work
breaking-changes.md Changes that require admin action after upgrade
```
- If the version directory does not exist yet, create it and both files with an empty heading:
+ If the version directory does not exist yet, create it and all three files with an empty heading:
```markdown
# Features — {version}
```
```markdown
+ # Fixes — {version}
+ ```
+
+ ```markdown
# Breaking Changes — {version}
```
+ ## Choosing the File
+
+ Pick by what the reader gets, not by how the work was labelled or which branch it came from:
+
+ | The change… | File |
+ | ------------------------------------------------------------------------ | --------------------- |
+ | lets someone do something they could not do before | `features.md` |
+ | makes something existing faster, clearer, or easier — nothing was broken | `features.md` |
+ | makes something work that was supposed to work already | `fixes.md` |
+ | closes a security hole in shipped behaviour | `fixes.md` |
+ | requires an admin to act during or after the upgrade | `breaking-changes.md` |
+
+ Two rules settle most of the hard cases:
+
+ - **One entry, one file.** A change that both fixes a bug and adds a capability goes wherever its
+ headline belongs — do not write it twice. A breaking change is always documented as a breaking
+ change, even when it is also a fix.
+ - **Titles say what is true now, not what was wrong.** Both files use the same voice, so
+ "Chat exports no longer lose attachments" belongs in `fixes.md` on the strength of what it does,
+ not because the title contains "no longer".
+
+ When it is genuinely ambiguous, ask: would an admin reading this be *relieved* (fix) or *interested*
+ (feature)? Relief goes in `fixes.md`.
+
## Entry Format
Each entry is a `##` level heading. Keep it product-oriented — what changed and what it enables,
not implementation details.
```markdown
## Short Title
One or two sentences describing what this does and why it matters to admins or users.
- Key detail 1
- Key detail 2
**Before upgrading:** Migration step if any (breaking changes only).
```
Include a configuration or API example only when admins need to take action.
## Writing Style
- **Audience:** admins and operators who read the in-product changelog. Not developers.
- **Tense:** present tense ("Admins can now…", "The sidebar now…").
- **Concise:** one paragraph plus bullets maximum. No filler phrases.
- **Scope:** omit internal refactors, dependency bumps, and test changes unless they have
a visible effect.
+ - **Fixes name the symptom.** An admin recognises the bug by what they saw, not by the cause, so
+ lead with the symptom and only then the reason: "The admin start page showed only grey
+ placeholders on installations without internet access — the update check had no timeout."
## Workflow
1. Identify the version (see above).
- 2. Read the existing `features.md` for that version to avoid duplication.
- 3. Read the code changes to understand the user-visible impact.
- 4. Append the new `##` entry to the appropriate file.
- 5. For breaking changes: always include a **Before upgrading:** migration note.
+ 2. Decide which file the entry belongs in (see **Choosing the File**).
+ 3. Read the existing entries in that file for that version to avoid duplication.
+ 4. Read the code changes to understand the user-visible impact.
+ 5. Append the new `##` entry to that one file.
+ 6. For breaking changes: always include a **Before upgrading:** migration note.
## When to Use
Use this skill proactively whenever you implement:
- - A new admin page, section, or feature
- - A change to configuration schema (new fields, renamed fields, removed fields)
- - A change to API behavior that operators rely on
- - A security improvement or bug fix that users/admins would want to know about
+ - A new admin page, section, or feature → `features.md`
+ - A change to configuration schema (new fields, renamed fields, removed fields) →
+ `features.md`, or `breaking-changes.md` when existing installs need action
+ - A change to API behavior that operators rely on → `features.md` or `breaking-changes.md`
+ - A bug fix or security fix that users/admins would want to know about → `fixes.md`
- Anything that appears in the admin "Needs your attention" feed
Skip for: pure refactors with no visible behavior change, dependency bumps, test additions,
comment/documentation-only changes.
+
+ ## Plumbing
+
+ The in-product changelog reads these files directly, so a new file name is not picked up on its own.
+ `server/routes/admin/changelog.js` chooses which files to read and
+ `client/src/features/admin/pages/AdminChangelogPage.jsx` renders each section — both must know
+ about any file added here.