| name | writing-release-notes |
| description | Use whenever adding, writing, drafting, or fixing a release note in the Actual Budget repo. This is the changelog entry that ships with a code change, living as a Markdown file in `upcoming-release-notes/`. Trigger for asks like "add a release note", "write the changelog entry", "add the release note for this PR/change", "create the upcoming release note", or any time finishing a user-facing change in this repo where a release note is the natural next step. These notes are published for humans to read, so they must be short, plain-language, and free of technical detail. Writing them like a commit message or with implementation jargon produces entries that get flagged and rewritten in review. |
Writing Release Notes for actualbudget/actual
Release notes are the user-facing changelog. Each code change adds one Markdown file to upcoming-release-notes/, and these get collected into the published changelog at the next release. The authoritative source is the Writing Good Release Notes section of packages/docs/docs/contributing/index.md. Read it if anything below is unclear.
The file
Create upcoming-release-notes/<slug>.md, where <slug> is a short, descriptive kebab-case slug naming the change (e.g. add-payee-autocomplete.md, fix-mobile-category-delete.md). Do not use a PR number, since the PR link is resolved automatically at release time. (Numeric filenames like 1234.md still work, but a slug is preferred.)
---
category: Features
authors: [YourGitHubUsername]
---
Add payee autocomplete to the transaction entry form
category: exactly one of Features (new feature), Enhancements (improvement to an existing feature), Bugfix (bug fix), or Maintenance (internal change with no user-visible effect).authors: array of the GitHub username(s) who did the work.
Writing the entry
The body is the changelog line. It is read by everyday users, not developers.
- One sentence. Short and clear. No paragraphs, no bullet lists, no long prose.
- Plain language, no technical detail. Describe what changed for the user, not how it was built. Avoid file names, function names, internal component names, and implementation jargon. (Exception:
Maintenance entries may be technical, since they are for internal changes.)
- Phrase it as a command. Start with a present-tense verb: "Add …", "Fix …", "Show …", not "Added …" or "Adds …".
- Generally match the PR title, but reword it if that reads more clearly to a user.
Good: Fix incorrect balance when reconciling an account with future transactions
Too technical: Fix off-by-one in reconcileTransactions() when txn.date > today
