Skip to content
Skills Library
Programming · Building & coding

backporting

/backporting

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, version-suffixed changesets, and the backport commit/PR shape, with real exemplars.

Repository
editor ↗
Licence
MIT
Last repository change
21.10.2026

Assessment and security

90/ 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.
Content25 / 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 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, version-suffixed changesets, and the backport commit/PR shape, with real exemplars.

Original author description

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, version-suffixed changesets, and the backport commit/PR shape, with real exemplars.

How it works

  1. Branch layout
  2. When to backport
  3. Procedure
  4. Commit shape
  5. PR shape
  6. After merge
Original SKILL.md headings · 35 lines, 607 words
SKILL.md preview
---
name: backporting
description: 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, version-suffixed changesets, and the backport commit/PR shape, with real exemplars.
---

# Backporting fixes

## Branch layout

`main` carries the current major, and the upcoming major is prereleased from `next` (see the `next-branch` skill). Older majors live on maintenance branches named `editor-v<N>.x` (currently `editor-v6.x` and `editor-v7.x`). Each maintenance branch has its own working release pipeline: `release.yml` on that branch triggers on pushes to itself, and the changesets bot opens "Version Packages" PRs from `changeset-release/editor-v<N>.x`. Merging a backport PR that carries a changeset is all it takes; no manual publishing.

## When to backport

A fix lands on `main` and the bug also exists on an older line that consumers still run. Backporting is per-branch: a bug present on both v6 and v7 gets two backport PRs, one per branch (#2919 and the equivalent v7 port shipped separately).

## Procedure

1. **Worktree per backport**, branched off the maintenance branch: `git worktree add ../editor-<change>-v6 -b <change>-v6 origin/editor-v6.x`. Branch name is the change name with a `-v6`/`-v7` suffix. Run `pnpm install` and build the affected package before testing; the branch's dependency tree differs from `main`'s.
2. **Verify the branch carries the bug before porting anything.** Find the culprit commit on the branch (`git log` for the regression source) or run the fix's test against the unpatched branch and watch it fail. If the bug does not reproduce, there is nothing to backport; say so and stop.
3. **Port the fix, adapting to the branch.** Cherry-pick the `main` commit when it applies cleanly, otherwise re-apply by hand. The old line often differs structurally (different package splits, older APIs); each adaptation is deliberate and gets named in the commit and PR (#2919: the test imports `defineSchema` from the package root because v6 predates the `@portabletext/schema` split).
4. **Port the tests and red-verify on this branch.** The pinning tests come along and must fail on the unpatched branch, the same red-verification bar as `main` (see the `writing-tests` skill). "Red-verified on this branch" belongs in the commit body.
5. **Write a fresh changeset**, patch bump, slug suffixed with the line (`readonly-selection-sync-v6.md`). The consumer prose is the same as the `main` changeset (see the `changesets` skill); the release pipeline on the branch turns it into a patch release of the old major.
6. **Run the same gates as any change**: `pnpm check:types`, `check:lint`, the affected package's tests, `pnpm build`, root `check:format` and `check:knip`.

## Commit shape

Same subject as the `main` commit, no version suffix. The body opens with "Backport of the fix that shipped on main." and then carries the full mechanism prose per the `commits` skill; a backport body must stand on its own because the branch's history never contains the `main` commit. Close with the red-verification note and any branch adaptations. Exemplars: `7f2b3b5de` (v6), `76d57a094` (v7).

## PR shape

- Draft PR with `--base editor-v<N>.x`. Title is the commit subject, optionally suffixed "(v6)"/"(v7)" to disambiguate in PR lists (#3151, #2919).
- The body is the `main` PR's narrative, then a closing paragraph that names it a backport: "Backport of #NNNN to the `editor-v6.x` line", why the branch carries the bug (the culprit commit is present in which shipped version), and the adaptations. #2919's closing paragraph is the exemplar:

> Backport of #2918 to the `editor-v6.x` line, which carries the same regression (`2a3e03934`'s early return is present in 6.6.6). Same one-line gate yield, same two pinned scenarios, red-verified on this branch; the only adaptation is the test importing `defineSchema` from the package root since v6 predates the `@portabletext/schema` split.

## After merge

Nothing manual. The push to the maintenance branch triggers its release workflow, the changesets bot opens "Version Packages" on `changeset-release/editor-v<N>.x`, and merging that PR publishes the patch release of the old major.

Versions

The database has no other skills named backporting.

Database snapshot: 13.11.2026 · package version 49e9847803c6 (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

  • 100changesets
    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…
  • 100backport
    Use this skill when backporting a merged CPython change to a maintenance branch (3.14, 3.13, etc.) - whether invoked as /cpython:backport <version> [PR], asked to backport or cherry-pick a fix from main, or handling a failed automated miss-islington backport. Produces a…
  • 100pr-backport
    Backport a merged PR to a release branch. Use this when you need to cherry-pick a fix or feature into an older branch.
  • 100next-branch
    How the `next` prerelease branch for the upcoming editor major works in the Portable Text Editor monorepo. Use when targeting a PR at the next major, handling the `sync/main-into-next` PR or its conflicts, deciding whether to merge "Version Packages (next)", or cutting the…
  • 100backport-pr
    Backport a merged PR to a maintenance major branch (v10 by default) in getsentry/sentry-javascript. Cherry-picks the PR's squash-merge commit onto the target branch, namespaces the commit/PR title scope (e.g. fix(core) -> fix(v10/core)), opens a draft backport PR, and documents…
  • 100backport-pr
    Backport a merged Next.js pull request from canary to an LTS release branch (releases/lts/active or releases/lts/maintenance). Use when the user asks to backport, cherry-pick, or open a backport PR from a PR number to an older Next.js version. Covers finding the merged PR…

Feedback and reports

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