mirror of
https://github.com/CherryHQ/cherry-studio.git
synced 2026-07-04 05:00:00 +08:00
461e45d133
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Co-authored-by: fullex <106392080+0xfullex@users.noreply.github.com> Signed-off-by: jd <59188306+zhangjiadi225@users.noreply.github.com>
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.mdtoYYYY-MM-DD-<brief>.md - Fill the frontmatter and body. See "Field reference" below
- If
What the user should dois not yet decided, writeTBD - 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.