docs/release-notes-guidelines.md
Rama master · réplica de lectura del repositorio original.
# Writing iTerm2 Release Notes
Release notes live in `docs/notes-<version>.txt` (cumulative, since the previous release) or `docs/notes-<version>beta<N>.txt` (per-beta diff, since the previous beta). They are **plain text, max 50 columns per line**.
## Audience
The reader is a **regular user or beta tester** who:
- Uses iTerm2 actively and reads release notes.
- Has **not** participated in development.
- Has **not** read the source code or commit history.
- Knows the names of features they already use, but not internal terminology.
Every entry must be self-explanatory to someone who only knows what iTerm2 looked like at the previous release.
## What to include
**Include:**
- Significant new features (a major UX change, a new panel, a new escape sequence, a new API).
- Improvements to existing features users will notice (faster, more options, better defaults, expanded scope).
- Bug fixes that affect features that **already shipped**.
- Performance, energy, and memory work that users will feel.
**Omit:**
- Implementation details (XPC re-org, internal symlinks, helper hooks, refactors, retain-cycle fixes that aren't user-visible).
- Advanced settings. These are off the beaten path and not release-note material.
- Developer-only features (env vars meant for switching between iTerm2 builds, etc.).
- Sub-features of a brand-new feature. If the parent is new, readers will discover the parts on their own.
- Bug fixes for features that are **also new in this release**. Readers have never seen the broken version; listing the fix just adds noise.
## Verify what's actually "new"
Before describing something as "improved", "now", "no longer", or "retuned", confirm the underlying feature existed in the previous release:
```sh
git ls-tree -r v<previous-tag> | grep -i <feature>
git grep -i <SymbolName> v<previous-tag>
```
If the feature itself shipped in this release, frame it as a brand-new capability — not as a refinement to something readers haven't seen.
This applies recursively: if `Workgroups` is new, then "the workgroup toolbar", "workgroup peers", "the Code Review prompt overlay", and any related concepts are also new — don't reference them as if they pre-existed.
## Section structure
Use these sections in order. Skip any that have no content.
1. **`Major New Features:`** — headline items. One short paragraph each: what it is and how to get to it. Don't enumerate every sub-feature.
2. **`New Features:`** — smaller new capabilities (a new escape sequence, a new panel, a new Python API, a new docking option). A new menu item that just exposes existing behavior is rarely a new feature.
3. **`Improvements:`** — tweaks to existing features (added options, better precision, broader scope). Energy, performance, and resource-usage wins also go here.
4. **`Bug Fixes:`** — fixes to behavior in features that pre-dated this release.
## Writing each entry
### Length
- One bullet, one idea. Aim for 1–3 lines.
- For a new feature, say **what it does** and **where to find it** (menu path, setting path, or escape sequence). Don't narrate the internal machinery or rationale.
- Don't paste the commit message. Rewrite from the reader's perspective.
### Voice
- Plain English. Avoid internal terminology. Examples of jargon to translate:
- "right gutter" → "side panel" / "alongside the terminal"
- "peer" → "companion session" / describe the relationship in prose
- "in-session prompt overlay" → "the prompt panel that appears before…"
- "cc-status hook", retain-cycle fixes, KVO refactors, XPC plumbing → omit
- Use **Title Case for feature names**: Smart Selection, Smart Selection Action, Workgroups, Code Review, Quick Look, Special Exceptions, Edit Session, Clippings, etc.
- Use **curly quotes** (`“ ”`, `‘ ’`) for user-visible quoted text. Use straight quotes only inside literal shell syntax (e.g. `$'…'`) or literal program output (e.g. `"unmatched '"`). Per CLAUDE.md, don't use `"` in user-visible strings except as the shorthand for inches.
### Order of introduction
If a bullet mentions feature X, X must already be familiar — either because it's pre-existing or because an earlier bullet introduced it. Put introductions before detail items.
For example, introduce the Clippings panel as a new feature **before** mentioning the `it2 add-clipping` subcommand that posts to it.
### Group like fixes
Collapse repetitive low-detail items:
- Multiple crash fixes → `- Fix various crashes.`
- Multiple memory leaks → `- Fix various memory leaks.`
- Multiple hangs → `- Fixed various hangs that could cause a beachball (X, Y, Z).`
## Format
- **50 columns** max. Hard-wrap.
- Bullets start with `- ` and continuation lines are indented two spaces.
- One blank line between sections.
- File names:
- `notes-<version>.txt` — cumulative, relative to the previous stable.
- `notes-<version>beta<N>.txt` — per-beta diff, relative to the previous beta.
- After creating a new notes file, `git add` it (per CLAUDE.md).
## Maintaining the cumulative file across releases
`docs/notes-3.7.txt` is the **running cumulative file** for the current
line: day to day you append new items to it, and it should contain
**only unreleased changes** — things that have not shipped in any
released build yet.
- **Never repeat a published item.** Once a change ships in a stable
release (or a beta the reader may have installed), it must not appear
in the notes for a *later* release. Re-listing it just tells readers
about something they already have.
- **Trim on release.** When a release is cut, the items it shipped
become published. Remove them from the cumulative file so what
remains is only the still-unreleased work for the next version. The
baseline for "already published" is the notes of the release that
just shipped (its `notes-<version>.txt` / `notes-<version>beta<N>.txt`).
- **Nothing is lost by trimming.** Every shipped version's notes are
preserved in its own per-version file and in git history. The
cumulative file is a working set, not an archive.
- **Verify against what actually shipped, not against wording.** The
cumulative file and the per-version files are written independently,
so the same change is often worded differently in each. Decide what
is published by the *commit* (is it in the shipped tag?), not by
matching bullet text. A feature documented late can describe code
that shipped in an earlier release — in that case the bullet is
published even though the doc commit is recent. Split such write-ups:
drop the parts already shipped, keep the parts that are new.
### Branches
- **master** accumulates all development; its `notes-3.7.txt` holds
every unreleased item destined for the next build off master (whose
version may not be known yet — a placeholder header is fine).
- **`release_x.y.z`** branches are cut from master and take
cherry-picks. On a release branch, `notes-3.7.txt` should contain
only what is new **since the previous release on that line** —
typically just the handful of fixes cherry-picked for that patch.
- Because 3.7.x patch releases cherry-pick a subset of master's
commits, "unreleased on master" is not simply "the newest commits."
Compare by commit against the shipped tag (e.g. subject match or
patch-id) to find what a release actually included.
## Pre-commit checklist
- [ ] Each entry makes sense without reading the source or commits.
- [ ] No internal jargon ("right gutter", "peer", "in-session overlay", hook names, etc.).
- [ ] No advanced-setting bullets.
- [ ] No developer-only bullets.
- [ ] No implementation-detail narration (internal machinery, refactors, rationale) — just what the reader observes.
- [ ] No item that already shipped in an earlier release; the cumulative file holds only unreleased changes.
- [ ] No bug-fix bullets for features that are themselves new in this release.
- [ ] Improvements are under `Improvements:`, not `Bug Fixes:`.
- [ ] Crashes / memory leaks / hangs are collapsed into single bullets.
- [ ] Feature names are Title Case.
- [ ] Curly quotes used everywhere except inside literal shell/error text.
- [ ] Every line ≤ 50 columns.