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.
- Author
- portabletext ↗
- Repository
- editor ↗
- Licence
- MIT
- Last repository change
- 21.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 21.10.2026, without references to retired models or APIs.
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
- Branch layout
- When to backport
- Procedure
- Commit shape
- PR shape
- After merge
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…