Breaking Changes Log

Internal record of v2 changes that affect how users use the app. Entries here are working material — at v2.0.0 release time they are aggregated and translated into the Chinese user-facing release note, then discarded with v2-refactor-temp/.

When to add an entry

Add an entry when a v2 change is user-perceivable and affects how users use the app. Examples:

Type	Example
Removed	A built-in integration / page / setting is gone
Changed	Default model, default behavior, or interaction flow is different
Moved	A setting or feature is now under a different menu / location
Data migration	A v1 field is dropped, transformed, or no longer preserved
Shortcut	A keyboard shortcut, URL scheme, or CLI surface is changed
Platform	Minimum OS version, required external service, or network requirement is changed

When NOT to add an entry

Pure internal refactors with no user-visible impact. The user cannot tell these happened:

IPC channel renamed / consolidated
Service split, lifecycle migration, decorator changes
Drizzle schema microchanges that round-trip identically through migration
Internal type renames, file relocations under src/main/services/

If unsure, err on the side of recording — easier to drop a notice during release prep than to recover a missed change.

File naming

YYYY-MM-DD-<brief-kebab-case>.md

Date is the entry author date (when you create the file), not PR merge date — keeps naming stable across rebases and reverts
Brief is a short kebab-case description, ≤ 6 words
Examples: 2026-04-29-remove-bilibili-integration.md, 2026-04-29-default-model-changed-to-gemini.md

Authoring

Copy _template.md to YYYY-MM-DD-<brief>.md
Fill the frontmatter and body. See "Field reference" below
If What the user should do is not yet decided, write TBD
Commit as part of the PR that introduces the change

Field reference

Field	Required	Meaning
`title`	yes	Short, user-visible headline. Not a commit subject — write what the user would notice
`category`	yes	One of `removed`, `changed`, `moved`, `data-migration`, `shortcut`, `platform`, `other` — for grouping at release time
`severity`	yes	`breaking` = user must take action / will be confused; `notice` = user should know but the app keeps working
`introduced_in_pr`	yes	`#<PR number>`; if no PR (direct push), use the commit hash
`date`	yes	`YYYY-MM-DD`, when this entry was authored
`What changed`	yes	1–3 sentences. Concrete user-visible behavior, not implementation
`Why this matters to the user`	yes	What will the user notice, when, and where
`What the user should do`	yes	Workaround, replacement feature, manual step, or `nothing — automatic`. `TBD` allowed
`Notes for release manager`	no	Caveats, edge cases, related entries to merge, screenshots to attach

Language

All entries are in English. The Chinese translation happens once at release time, not per entry.

Lifecycle

PR introduces user-impacting change
  → author drops an .md fragment here
  → fragments accumulate during v2 development
  → at v2.0.0 release prep, release manager aggregates, translates, polishes
  → published as Chinese user-facing release note
  → fragments are discarded together with v2-refactor-temp/

This mirrors the .changeset/ fragment-then-discard pattern. The fragments are not the permanent record — the published release note is.