---
name: port-changes
description: Port a change (PR or branch) onto the currently checked-out Saleor branch — forward-port UP (3.22 → 3.23 → main) or backport DOWN (main → 3.23 → 3.22). Use when asked to port, forward-port, backport, or cherry-pick a change to this branch/version.
---

# Porting a change onto this branch

**One run = one port, onto the branch already checked out.** The current branch is the destination —
never switch, create, or rename branches, and never chain hops. A multi-hop port
(`3.22 → 3.23 → main`) is separate runs on separate workspaces; if the user asks for more than one
hop, do the one that matches this branch and tell them to ask again on the next branch.

## 1. Establish source and direction

- The user points at a PR (`gh pr view <n> --json baseRefName,files`, `gh pr diff <n>`) or a branch.
- Source = where the change was **originally authored** (PR base). Destination = the current branch
  (`git branch --show-current`; `main` is the next unreleased version — check
  `# 3.X.0 [Unreleased]` at the top of `CHANGELOG.md`).
- **UP (forward-port):** source older than destination (`3.22` → `3.23`/`main`).
- **DOWN (backport):** source newer than destination (`main` → `3.23`).
- State the direction you inferred in your first message, so a wrong guess is caught early.

## 2. GraphQL: pin to the oldest version that ships it

The `ADDED_IN_*` marker names when the field/mutation first became available, not which branch you
are editing. Constants live in `saleor/graphql/core/descriptions.py`.

- A change first released in 3.22 keeps `ADDED_IN_322` here too, even on `main`.
- A DOWN port to a version older than the marker makes the field ship earlier than the marker
  claims — use the older version's marker here, and tell the user the source branch's marker needs
  the same correction (don't go edit it yourself).
- If the introducing version is ambiguous, **ask the user**. Don't guess.
- Regenerate `saleor/graphql/schema.graphql` — see `saleor-graphql-api-change`.

## 3. Migrations: keep the oldest branch's identity, merge on top

Migration numbering diverges per branch, so a straight cherry-pick produces a broken graph.

- The migration keeps the **file name and number it has on the oldest branch that ships it** —
  never renumber or rewrite a migration that already shipped.
- On an UP port, if that number now collides with migrations that landed only here, resolve the two
  leaves with a **merge migration** (`python manage.py makemigrations --merge`) — see existing
  `*_merge_*.py` files for the shape.
- On a DOWN port where this branch is now the oldest to ship it, pick the number that fits here and
  tell the user the newer branches must reuse this name.
- Zero-downtime rules still apply: `CREATE INDEX CONCURRENTLY` in its own `atomic = False`
  migration, schema and data migrations split. See `saleor-migrations`.

## 4. CHANGELOG: only on the branch that introduces the change

- Edit `CHANGELOG.md` **only if this branch is the first release to ship the change**.
- UP port of something already released in 3.23 → **no CHANGELOG edit here**; it was already
  announced.
- DOWN port → add the entry here (this release now introduces it) and tell the user to drop it from
  `main`'s `[Unreleased]` section.
- `main`'s CHANGELOG is edited only when the change debuts in `[Unreleased]` and is not backported.

## 5. Before finishing

- Tests for the ported code pass (`pytest --reuse-db <paths>`, see `pytest-runner`).
- Schema file regenerated if GraphQL changed; `pre-commit` clean.
- If this branch lacks a dependency the source relied on, **stop and report it** — don't invent a
  partial port.
- Report anything the user must fix on the other branches (marker corrections, migration names,
  CHANGELOG moves) — you are not touching those branches.

Do not push. Commit only if explicitly asked.