| name | fantasia-changelog-en-us |
| description | Maintains the English in-app changelog at i18n/en-US/documents/changeLog.md in strict sync with package.json version, without any automatic version bumping. Changelog text must be user- or release-relevant only—never internal QA, Git meta (commits/pushes), or “updated changelog”. Prefer editing the log in the same commit as the work, before push. Use after substantive app, UX, or user-facing docs changes, or when the user asks for release notes. |
Changelog and version (changeLog.md + package.json)
Files
- Changelog: changeLog.md — in-app via
documents.changeLog
- Other locales: mirror path (e.g. fr changeLog.md) — edit only when user explicitly asks to mirror; default =
en-US only
- Canonical semver: package.json
version
- Planning context:
.cursor/plans/ matching current version
When to update
After substantive user/operator-visible work: feat, fix, notable shipped dependency changes described as product change. Skip trivial-only edits unless user wants log.
What must not go into changeLog.md
In-app changelog = end users. Omit bullets that only record:
- Re-running
yarn testbatch:verify, lint, unit, Electron build, Playwright, Storybook, testbatch:ensure:*
- “All tests passed”, “pipeline green”, packaging QA meta
- Git/housekeeping: commits, pushes, “updated changelog”
Verification belongs in commits/PRs — not changelog. Dependency refresh bullets: describe what changed, not test matrix.
Changelog timing vs Git
- Default: update in same working tree + same commit as feature/fix; finish before
git commit and git push
- Avoid: trailing changelog-only commit after push — rare typo/section fixes only (testing-terminal-isolation.mdc)
Pre-changelog workflow gate
- Full quality gate —
yarn testbatch:verify in one terminal (testing-terminal-isolation.mdc). Dev scoped gate during edits does not substitute. Changelog-only follow-up touching only i18n/*/documents/changeLog.md: may skip if full gate already passed after substantive edits and tree otherwise unchanged.
- Affected
src/components/**: Storybook stories/mocks aligned (yarn storybook:run). Skip for changelog-only repair.
- Draft/update entries.
Plan-context check
- Read live
package.json.version → pkg
- Scan
.cursor/plans/ for filename/body matching pkg
- Use plans as supporting context only
Version policy (strict)
- Re-read
version from package.json immediately before edit → pkg (no cached value)
- Topmost changelog heading: first
## X.Y.Z semver below title
- NEVER, EVER, UNDER ANY CIRCUMSTANCES auto-bump or infer new version
- Changelog headings follow
package.json exactly unless user explicitly requests manual version change
Heading vs pkg
| Case | Action |
|---|
| No semver heading yet | Add ## {pkg} - Short title |
Top heading equals pkg | Append bullets under existing ### only |
Top heading lower than pkg | New ## {pkg} - Short title section above |
Top heading higher than pkg | Fix changelog to match pkg; do not change package.json unless user asks |
Section headings (###)
- Only headings with ≥1 real bullet
- No empty categories, no “None” placeholders
- Omit entire
### when nothing to say for this release
Bullet style
- One line,
- prefix; product-facing wording
- Add
### only when adding bullets under it
Translated changelogs (strict)
- Never edit
i18n/<locale>/documents/changeLog.md for any non-en-US locale unless user explicitly asks to mirror
- Default scope =
en-US only
- Translations, i18n key work, or other locale edits do not trigger changelog mirror
- When user does ask: mirror only maintained locale changelogs, reuse each locale's existing section heading + product-name translations
vue-i18n and changeLog.md (required)
changeLog.md = vue-i18n message string. { … } = interpolation placeholders — invalid tokens throw at runtime (Invalid token in placeholder).
- Do not put literal
{...} unless valid vue-i18n placeholder syntax (almost never here)
- Avoid JS/TS object literals, API option objects with braces in prose
- Describe globs in words — list extensions, no brace expansion
- Literal
| needs vue-i18n escape (\\| in TS source where needed)
- Mention braces as “open brace … close brace” if documentation requires
Related
Types
Shared types → types/. See types-folder.mdc.
