Skip to content
Skills Library
Programming · Writing

changesets

/changesets

How to write changesets in the Portable Text Editor monorepo. Use whenever adding a .changeset/*.md file or deciding whether a change needs one. Covers bump selection (patch/minor/none), the subject-mirrors-commit rule, consumer-facing prose style, and API changesets, with real exemplars from the repo history.

Repository
editor ↗
Licence
MIT
Last repository change
21.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 21.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

How to write changesets in the Portable Text Editor monorepo. Use whenever adding a .changeset/*.md file or deciding whether a change needs one. Covers bump selection (patch/minor/none), the subject-mirrors-commit rule, consumer-facing prose style, and API changesets, with real exemplars from the repo history.

Original author description

How to write changesets in the Portable Text Editor monorepo. Use whenever adding a .changeset/*.md file or deciding whether a change needs one. Covers bump selection (patch/minor/none), the subject-mirrors-commit rule, consumer-facing prose style, and API changesets, with real exemplars from the repo history.

How it works

  1. When and what bump
  2. Shape
  3. Exemplars (real, from the repo history)
Original SKILL.md headings · 125 lines, 1,234 words
SKILL.md preview
---
name: changesets
description: How to write changesets in the Portable Text Editor monorepo. Use whenever adding a .changeset/*.md file or deciding whether a change needs one. Covers bump selection (patch/minor/none), the subject-mirrors-commit rule, consumer-facing prose style, and API changesets, with real exemplars from the repo history.
---

# 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

```md
---
'@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."

### minor: new API with enumerated name + example

````md
---
'@portabletext/editor': minor
---

feat: add `editor.dom.getPointAtCoordinates`

Pass viewport coordinates (for example a pointer event's `clientX`/`clientY`) and get back where a click at those coordinates would place the caret, as an editor selection point, or `null` when the coordinates don't hit the editor's content:

```ts
const point = editor.dom.getPointAtCoordinates({
  x: event.clientX,
  y: event.clientY,
})
// {path: [{_key: 'b1'}, 'children', {_key: 's1'}], offset: 3}
```
````

It's the counterpart of `editor.dom.getSelectionRect`: that one turns a selection into pixels, this one turns pixels back into a point. Behavior guards and actions get it on their `dom` argument.

````

Why it's good: the export is named, the example shows input AND output shape, and the
"counterpart of" framing places the API in the consumer's existing mental model.

### patch: behavior fix, consumer-observable framing

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

fix: resolve `getSibling` when `blockIndexMap` misses or disagrees with the tree

`getSibling` previously returned `undefined` for siblings the tree
plainly has when the anchor's path was absent from the block-index
map, and could return the wrong sibling when the map was stale. It now
verifies the mapped position against the tree and falls back to a
linear scan, matching `getNode` and `getChildren`. Paths addressing
the anchor by numeric index now resolve instead of returning
`undefined`.
````

Why it's good: states the wrong observable outputs (`undefined` where a sibling exists, wrong sibling), then the new contract, and anchors it to sibling APIs the consumer already trusts ("matching `getNode` and `getChildren`").

## Multi-PR release trains (stacks)

When a major lands as a stack of PRs feeding one Version Packages release, three extra rules apply; each was learned from a real incident during the v8 stack:

- **A changeset must be true of the release, not just its PR.** Before pushing, audit claims about untouched surface ("X stays", "remains exported but is deprecated", "Y keeps composing") against the other pending changesets: a sibling PR in the same train may remove exactly that surface, and the changelog would assert both. (The `remove-render-list-item` changeset promised `data-list-item`/`data-level` stay; the unified-DOM changeset removes them.)
- **Changesets are keyed to consumer-observable changes, not PRs.** A PR that completes a story an earlier pending changeset began amends that changeset instead of adding a sibling; pending changesets are ordinary files on `main` until released. (The props-shape-types PR added no changeset: `remove-render-style` absorbed `BlockStyleRenderProps`, since prop and types leaving together is one change to the consumer.)
- **Migration advice must name a reader you can point at.** If no consumer demonstrably uses the pattern the sentence addresses, delete the sentence; speculative hand-holding is noise wearing a helpful face. (An invented `Pick<BlockStyleRenderProps, ...>` consumer got a personalized migration note; nobody Picks from a callback-payload type.)

## Anti-patterns

- First line paraphrasing instead of mirroring the commit subject.
- Diagnosis prose ("the bug was in `updateBlock`'s reconcile...") — consumers don't care where it was, only what changed for them.
- Referencing tests, PR numbers, or issue-tracker tickets.
- A changeset for an internal refactor "just in case" — no observable change, no changeset.
- Bumping minor for a fix because it "feels big"; size ≠ semver.

## The canon

Past changesets are consumed on release; `packages/*/CHANGELOG.md` is where they accumulate. The `7.x` entries in `editor/CHANGELOG.md` are the reference set.

Versions

RepositoryScoreLicence
This page · portabletext/editor100MIT
TerminalSkills/skills100Apache-2.0
clerk/cli100MIT
lxsmnsyc/agent-skills100MIT
joelwohlhauser/blackbird90MIT
foldkit/foldkit90MIT

Database snapshot: 13.11.2026 · package version f8c9ce2cfa53 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100commits
    How to write commit messages in the Portable Text Editor monorepo. Use whenever committing here. Covers subject conventions, the dense mechanism-first body shape, commit-type selection (including the changeset⇒fix/feat rule), splitting, and fixup discipline, with real exemplars…
  • 90backporting
    How to backport a fix from `main` to a maintenance branch (`editor-v6.x`, `editor-v7.x`) in the Portable Text Editor monorepo. Use when a fix that shipped on `main` must also ship for an older major. Covers the branch layout, the verify-adapt-red-verify procedure,…
  • 100changeset
    Writes Changesets entries for a JavaScript or TypeScript monorepo. Detects the workspaces from pnpm-workspace.yaml or the package.json workspaces field, finds the packages changed on the branch, skips the ones ignored in .changeset/config.json, picks patch, minor or major for…
  • 100writing-changesets
    Use when writing a changeset, or before filing a PR in a repository that uses changesets.
  • 100changeset
    Creates changesets for semantic versioning. Use when adding changesets, preparing releases, determining version bumps (patch/minor/major), generating changelog entries, or documenting breaking changes.
  • 100creating-changesets
    Creates changesets for semantic versioning. Use when adding changesets, preparing releases, determining version bumps (patch/minor/major), generating changelog entries, or documenting breaking changes.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.