changelog
Use before adding or editing a CHANGELOG.md line in a pull request. Rules for what earns a line (only what a learner can see or feel), how to word it, and what never does (CI, workflows, tools, tests, refactors, deck content, docs). Docs-only commits and pushes need no line.
- License 许可
- GPL-3.0
- 最近更新
- 2026-11-15
- Stars
- ★ 4
- Forks
- 0
01 前言 Front Matter
- name
- changelog
- description
- Use before adding or editing a CHANGELOG.md line in a pull request. Rules for what earns a line (only what a learner can see or feel), how to word it, and what never does (CI, workflows, tools, tests, refactors, deck content, docs). Docs-only commits and pushes need no line.
03 SKILL.md 正文
The wiki is the source of truth for documentation: https://github.com/aaronified/fluenough/wiki
Writing the CHANGELOG line
Owner, 2026-11-13: "the last changelog for the app (the one that shows up at the start after an update) was very weird. a lot of the entries were simply CI (nothing else). the changelog writer needs to be wary of these mistakes, maybe add a skill for writing changelogs in each PR commit. pure doc commits do not need update in the changelog as they do not alter the app".
Who reads it
An app user, after an update. The app shows the headline of each entry of the
installed version as a bullet in a sheet on the first launch (#944;
whatsNewHeadlines in lib/core/updates/whats_new.dart), and the release
workflow publishes the same section as the release notes
(tools/prepare_release.py --notes). Write for a learner who has never seen
the repository.
What the app does with a line
- A line that starts with a bold phrase shows that phrase:
- **Headline.** detail. - A line that starts with a backtick is hidden in the app's sheet, but it is still in the release notes on GitHub. So a backtick does not make a line harmless; it only keeps it out of the sheet.
- Any other line is shown, cut at the first
(#123), colon, full stop and space, or spaced dash.- CI: test shard weights refreshed ...therefore shows as the bullet "CI". That is the mistake of 0.10.0. - The Release workflow refuses to run if a line breaks this rule
(
unreleased_problemsintools/prepare_release.py).
What earns a line
A change a learner can see or feel in the app: a new screen, button or setting, a behaviour that now works differently, a bug they could hit that is fixed. Form:
- One line:
- **Plain headline.** One plain sentence of what changes for the learner. - The headline is a few words, bold, ending in a full stop, and makes sense on its own as a bullet.
- No issue numbers, no file paths, no jargon (no "ONNX", "CTC", "shard", "pipeline", "refactor").
What never earns a line
CI, workflows, .github/, tools/, tests, refactors, internal plumbing that
no screen shows yet, deck content (new or filled decks, paths: it is content,
not a release), and docs. If unsure whether a learner could notice it, it is
developer-only: leave it out of the CHANGELOG. (Only if the owner asks for a
developer note, start it with a backtick, which hides it from the app's sheet
but not from the release notes.)
Pure doc commits and docs-only pushes need no CHANGELOG line, since they do
not alter the app. A change that touches code, a deck, decks/index.json or
the CHANGELOG itself is not docs only.
A pull request with nothing a learner can notice adds no line. The release workflow refuses an empty Unreleased section, so the owner is told when a release has nothing in it.
Structure
One heading of each kind per section: ### Added, ### Changed, ### Fixed.
Add the line under the existing heading in ## [Unreleased]; never open a
second ### Fixed (0.10.0 has two identical ones, with the same two lines in
both). A merge conflict in the CHANGELOG is resolved by keeping both sides'
lines under one heading, not by repeating the block.
Examples, from the 0.10.0 section
Good:
- **Find my level shows its result card at once, and the result is simpler.** The "See my result" pause is gone ...- **Search results by type, and topic pages.** The Decks tab's search shows a tab for each kind of result ...
Bad, with the fix:
- CI: test shard weights refreshed so the 8 shards finish together.Shown as the bullet "CI". Omit.- CI: the heavy placement suites run only when placement changes ...Omit.- tools/asr: Telugu on-device listener reference tools (#1004).A path, a tool. Omit.- .github/workflows/asr-export.yml: manual workflow that exports ...A workflow. Omit.- On-device listener: pure-Dart log-mel front end (#1004).Jargon, an internal piece no screen shows. Omit until the feature lands; then one line:- **Telugu on-device listening.** Install a Telugu listener from the Voices page and Say works offline.- Say works again: recording no longer runs ...; #1107.No bold headline and an issue number. Better:- **Say works again.** Recording no longer clashes with online recognition, so your voice is heard as before.- CI: the web smoke test no longer fails when the runner ...CI again. Omit.- A second
### Fixedblock repeating the first. Keep one.
Do not rewrite a released section: it is history.
Self-check before committing
- Is the change docs only? Then no line.
- Could a learner notice it in the app? If not, no line.
- Does the line start with
- **Headline.**in plain words? - No issue number, no file path, no jargon, no "CI", "tools", "workflow", "test"?
- One sentence of detail, saying what the learner now sees or can do?
- Is it under the one existing
###heading in## [Unreleased], not a new duplicate heading? - Does it say nothing about deck content?
04 同仓库更多 Skills
work-rating
Opt-in, only when the owner asks. Have an independent subagent rate a finished piece of work out of 10 against the user's own prompts. Never run it at the end of a task on your own; the PR's one review is enough (owner, 2026-10-12, 2026-10-22).
flutter-dart-code-review
Library-agnostic Flutter/Dart code review checklist covering widget best practices, state management patterns (BLoC, Riverpod, Provider, GetX, MobX, Signals), Dart idioms, performance, accessibility, security, and clean architecture. Use when reviewing Flutter or Dart code, whatever state management library the project uses.
build-deck
Use when building or extending a Fluenough deck, including writing the next planned unit of a language's B1 plan, a word unit or a grammar unit (a core in decks/<lang>/ plus its English layer in decks/<lang>/en/). Not for app code.