@@ -31,8 +31,10 @@ If the PR number is missing, ask for it. Do not guess.
3131 ` fix(cloudflare,deno,node): ... ` -> ` fix(v10/cloudflare,deno,node): ... ` .
3232- ** PR body** is a single line: ` Backport of: #<original-pr-number> ` .
3333- ** PR is opened as a draft.**
34- - ** Branch name** : ` ab/<major>-<short-slug> ` (personal rule is the ` ab/ ` prefix). Derive
35- ` <short-slug> ` from the original PR title, e.g. ` ab/v10-fix-log-flush-starvation ` .
34+ - ** Branch name** : ` backport/<major>-<short-slug> ` , where ` <short-slug> ` comes from the
35+ original PR title, e.g. ` backport/v10-fix-log-flush-starvation ` . If you already use a
36+ personal branch prefix (some contributors do, e.g. ` <initials>/... ` ), keep using it — only
37+ the base branch and commit/PR title conventions below are load-bearing.
3638- The changes come from the PR's ** squash-merge commit** on ` develop ` (one commit per PR),
3739 so a single ` git cherry-pick ` normally covers the whole PR.
3840
@@ -74,7 +76,7 @@ producing an empty commit.
7476### 2. Create the backport branch off the target major
7577
7678``` bash
77- git checkout -b ab /< major> -< slug> origin/< major>
79+ git checkout -b backport /< major> -< slug> origin/< major>
7880```
7981
8082### 3. Cherry-pick the merge commit
@@ -95,21 +97,12 @@ git cherry-pick <mergeCommit-oid>
9597- If the PR was ** not** squash-merged (multiple commits, e.g. a merge commit), cherry-pick
9698 each relevant commit in order, or use ` git cherry-pick -m 1 <merge-oid> ` for a merge commit.
9799
98- ### 4. Reword the commit to namespace the scope
100+ ### 4. Build and verify
99101
100- Rewrite only the subject line's scope to include the major; keep the body. Do ** not** add a
101- ` Co-Authored-By ` line or conventional prefix beyond what's described here — the backport
102- branch's first commit mirrors an existing commit rather than being new authored work.
103-
104- ``` bash
105- git commit --amend -m " <prefix>(<major>/<scope>): <original subject>" -m " Backport of: #<PR>"
106- ```
107-
108- Example: ` fix(v10/core): Fix logs flush timeout starvation with continuous logging `
109-
110- ### 5. Build and verify before pushing
111-
112- Run the repo's pre-commit checks so the backport branch is green:
102+ Run the repo's pre-commit checks. Do this ** before** finalizing the commit in step 5, because
103+ ` yarn format ` writes changes to the working tree — those fixes must end up inside the backport
104+ commit, not left dangling after it (otherwise you'd push an unformatted tree and CI would fail
105+ on a commit that doesn't match your local state).
113106
114107``` bash
115108yarn format
@@ -121,10 +114,30 @@ Run tests scoped to the touched packages when possible (full `yarn test` if unsu
121114target major's toolchain differs and a check fails for reasons unrelated to the change, note
122115it for the user rather than silently skipping.
123116
117+ ### 5. Finalize the commit (reword scope + fold in verification changes)
118+
119+ Stage anything ` yarn format ` /` yarn lint ` changed, then amend in one step: this both namespaces
120+ the subject scope with the major and captures the formatting fixes. Rewrite only the subject's
121+ scope; keep the body. Do ** not** add a ` Co-Authored-By ` line — the backport commit mirrors an
122+ existing commit rather than being new authored work.
123+
124+ ``` bash
125+ git add -A
126+ git commit --amend -m " <prefix>(<major>/<scope>): <original subject>" -m " Backport of: #<PR>"
127+ ```
128+
129+ Example subject: ` fix(v10/core): Fix logs flush timeout starvation with continuous logging `
130+
131+ Confirm the tree is clean so nothing is left uncommitted before you push:
132+
133+ ``` bash
134+ git status --porcelain # expect no output
135+ ```
136+
124137### 6. Push and open the draft PR
125138
126139``` bash
127- git push -u origin ab /< major> -< slug>
140+ git push -u origin backport /< major> -< slug>
128141
129142gh pr create \
130143 --draft \
@@ -144,7 +157,7 @@ gh pr comment <PR> --body "<major> backport: #<new-backport-pr>"
144157## Notes
145158
146159- Never push directly to ` develop ` , ` master ` , or the major branch. Work only on the
147- ` ab /<major>-...` branch and open a PR.
160+ ` backport /<major>-...` branch and open a PR.
148161- One PR per backport. If asked to backport several PRs, repeat the whole flow per PR (each
149162 gets its own branch and draft PR).
150163- If asked to backport to multiple majors at once (e.g. v10 and v9), do them as separate
0 commit comments