Changesets

Writing PTE changesets

When and what bump

• One changeset per user-facing change. Filename is slug-style, describing the change (get-sibling-map-fallback.md, catalog-cross-kind.md), not the ticket/PR.
• fix: / user-visible refactor → patch. New API → minor.
• No changeset for: internal-only refactors, tests, CI/tooling, dependency regrouping with no resolved-version change.
• New packages get no changeset: v1.0.0 is hand-published from the branch before the PR merges (plugin-typeahead-picker precedent); changesets manage it from 1.0.0 on.
• Corollary: a commit that ships a changeset is fix:/feat: (see the commits skill).

Shape

---
'@portabletext/editor': patch
---

<commit subject, verbatim, prefix and backticks included>

<blank line>

<1–2 paragraphs for the CONSUMER: present tense, observable behavior>

• First line repeats the commit subject verbatim. Since the frontmatter names the package, the commit subject (and thus this line) uses bare fix:/feat:, no scope.
• The prose is written for the consumer reading a changelog: what they observe, in present tense ("Backspacing through empty blocks ... no longer slows down"). Not the diagnosis, not test references, not PR numbers, not internal function archaeology, that lives in the commit body and PR description.
• API changesets enumerate the exact exported names and show a fenced usage example. Include a resolution-order list when the API has ordering semantics (see the defineX render-prop-types and '*' catch-all entries in editor/CHANGELOG.md).
• Call out the upgrade action explicitly when the change shifts something consumers iterate, switch over, or type against: "Code that iterates the map will see the new serialized-path keys", "exhaustive switches over event.type gain a case".
• Perf fixes state the numbers.
• Fix changesets show the case they fix, so a consumer recognizes their own code in it. When the bug depends on something the consumer writes (a schema, a document), a runnable fenced block right after the sentence stating the fix shows a minimal version of it and the public call that failed, with the old outcome in a comment (// Previously threw: TypeError: ...). Input alone is not enough: the reader must see which call to look for in their own code. Run the snippet against the old and new code before committing it. When the bug depends on an action (a keystroke, a paste), the changeset names the exact steps and content.
• Secondary behavioral changes shipping in the same release are named explicitly, in a plain sentence that belongs to the paragraph ("Removing a decorator from part of a selection made left to right also no longer marks the selection as backward."). Never behind a label such as "One additional change:" or "Also changed:": a label tacked onto every changeset reads as boilerplate.
• Banned vocabulary in changeset prose (and any artifact prose): "delta" (write "change") and "rides along"/"ride along" (name the change in a plain sentence instead).
• Small self-explanatory changes can be subject-only.

Exemplars (real, from the repo history)

patch: perf fix with numbers + a named secondary behavioral change

---
'@portabletext/editor': patch
---

fix(perf): resolve the `unset` selection fallback's nearest spans without a document scan

Backspacing through empty blocks, and any other edit that removes the node the selection sits in, no longer slows down with document size. Previously each such removal scanned the document from the start to find the nearest span; in large documents this made deleting empty lines feel sluggish (~267ms per backspace at 8,000 blocks, now ~20ms).

One narrow behavioral fix rides along: when the removed node was addressed by a numeric path, the fallback previously moved the selection to the document's first span; it now moves it to the actual nearest span.

Why it's good: observable symptom first ("backspacing ... no longer slows down"), numbers with context, and the secondary behavioral change named explicitly, last. One phrase in it is retired: this exemplar predates the ban on "rides along" and on labels, so imitate its structure (the secondary change named, last), not its wording. Today the last paragraph reads: "Removing a node addressed by a numeric path also moves the selection to the actual nearest span instead of the document's first span."