document-feature · diff
git:20260730.f8391d4 to git:20260915.49623fb
82 added, 52 removed. Audit A to A.
---
name: document-feature
- 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.
+ description: Use when a new feature, improvement, bug fix, or breaking change has been implemented. Adds an entry to docs/releases/next/ so it appears in the in-product admin changelog ("What's New") — or decides, with reasons, that nothing needs one.
user-invocable: true
---
# Release Documentation
- 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
+ Admins read `docs/releases/` as **Admin → What's New**. Every change that admins or end users can
+ see gets an entry there — in `docs/releases/next/`, and nowhere else.
- 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.
+ ## Where Entries Go
- ## Directory Structure
+ Always `docs/releases/next/`. It holds the notes for everything that has not shipped in a tagged
+ release yet, in three files:
```
- 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
+ docs/releases/next/
+ breaking-changes.md Changes that require admin action during or after the upgrade
+ features.md New capabilities and improvements (admin-facing and end-user-facing)
+ fixes.md Corrections to behaviour that was already supposed to work
```
- If the version directory does not exist yet, create it and all three files with an empty heading:
+ Numbered directories (`docs/releases/5.5.7/`) are frozen. They hold exactly what shipped in that
+ release and are created by the release pipeline from `next/` when the tag is cut. Never write into
+ one, never invent a version number, never read `package.json` to pick one — the tag decides.
+ If `next/` is missing (a fresh clone of an older branch), create it with the three files, each
+ holding only its heading:
+
```markdown
- # Features — {version}
+ # Features — Unreleased
```
```markdown
- # Fixes — {version}
+ # Fixes — Unreleased
```
```markdown
- # Breaking Changes — {version}
+ # Breaking Changes — Unreleased
```
+ ## Should This Be Documented at All?
+
+ Decide before writing. Skip when the answer to any of these is no:
+
+ 1. **Is it visible?** Refactors, dependency bumps, test changes, comment- or docs-only changes and
+ internal renames are not. Neither is a detail no admin or user would ever notice.
+ 2. **Did the behaviour ship?** A fix for something that only exists in `next/` — a feature merged
+ since the last tag, or introduced earlier in the same PR — is not a fix anyone experienced.
+ Do **not** add a `fixes.md` entry for it. If the fix changes what the reader should know (a
+ renamed setting, a limit, a default), edit the feature's existing entry; otherwise there is
+ nothing to write.
+ 3. **Is it already covered?** Read the target `next/` file first. One entry per capability per
+ release: a second PR on the same feature extends the existing entry — add a bullet, sharpen
+ the title — rather than adding a near-duplicate. Three entries titled "Answer-source badge fixed
+ for …" are one entry.
+
+ Being asked to run this skill is not a reason to write something. "Nothing to document" is a
+ valid outcome — say so, and say why.
+
## 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` |
+ | 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`.
+ 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.
+ Each entry is a `##` heading followed by its text. The heading is the entry's identity: it becomes
+ the link in the table of contents, so keep it unique within the file and make it say what the
+ reader gets. Prefix the area when the title alone would not place it (`Workflow Editor: …`,
+ `Outlook Add-in: …`).
```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.
+ Inside an entry, use `###` for sub-sections, fenced code for configuration and commands, and a
+ `>` quote for error text verbatim. Never start a line inside an entry with `#` or `##` outside a
+ code fence — it would begin a new entry. 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
+ - **Concise:** one paragraph plus bullets. No filler phrases, no implementation details.
+ - **Fixes name the symptom.** An admin recognises a bug by what they saw, not by its 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."
+ - **Wrap at 100 columns.** The page renders Markdown, so a line break inside a paragraph is just
+ wrapping.
## Workflow
- 1. Identify the version (see above).
- 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.
+ 1. Read the three files in `docs/releases/next/`.
+ 2. Decide whether anything needs documenting (**Should This Be Documented at All?**).
+ 3. Pick the file (**Choosing the File**).
4. Read the code changes to understand the user-visible impact.
- 5. Append the new `##` entry to that one file.
+ 5. Either extend the existing entry in place, or **append** the new `##` entry at the end of the
+ file. Never reorder, merge or rewrite other entries.
6. For breaking changes: always include a **Before upgrading:** migration note.
- ## When to Use
+ ## How Entries Become a Release
- Use this skill proactively whenever you implement:
+ Creating a GitHub release for a tag runs `scripts/finalize-release-notes.js` in the release
+ workflows:
- - 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
+ - The entries in `next/` at the tagged commit move to `docs/releases/<version>/` (only the files
+ that have entries), and a commit lands on the default branch. Entries merged after the tag stay
+ in `next/`.
+ - If `next/` has no entries, the release gets no directory and the changelog does not list it.
+ - `next/` is left in place with its three headings, ready for the next entry.
- Skip for: pure refactors with no visible behavior change, dependency bumps, test additions,
- comment/documentation-only changes.
+ Details: `docs/release-process.md`.
## 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.
+ - `server/utils/releaseNotes.js` — parses the `##` entries and versions; shared by the endpoint,
+ the release script and the tests.
+ - `server/routes/admin/changelog.js` — `GET /api/admin/changelog` (releases with counts) and
+ `GET /api/admin/changelog/:version` (one release's entries).
+ - `client/src/features/admin/pages/AdminChangelogPage.jsx` — the page.
+ - `scripts/finalize-release-notes.js` — publishes `next/` under a tag.
+
+ A fourth section file would need `RELEASE_SECTIONS` in `releaseNotes.js`, the `SECTIONS` table in
+ the page and this document to know about it.