mirror of
https://github.com/CherryHQ/cherry-studio.git
synced 2026-07-06 14:01:30 +08:00
e97480c4c9
Add an internal record for v2 changes that affect how users use the app. PR authors drop a fragment .md per change; the release manager aggregates and translates them into the Chinese user-facing release note at v2.0.0, then discards the fragments with v2-refactor-temp/. Also translate v2-refactor-temp/README.md to English and link the new directory from it.
74 lines
3.5 KiB
Markdown
74 lines
3.5 KiB
Markdown
# 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
|
||
|
||
1. Copy `_template.md` to `YYYY-MM-DD-<brief>.md`
|
||
2. Fill the frontmatter and body. See "Field reference" below
|
||
3. If `What the user should do` is not yet decided, write `TBD`
|
||
4. 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.
|