Skip to content

Commit d4faad8

Browse files
[llvm][docs] Reorder Stacked PR approaches in GitHub.rst
The 'user branches' approach now appears before the 'dependency note' approach, as it makes reviewing easier. Add notes on requiring commit access for the former and on the disadvantage of the latter.
1 parent 21aa7b8 commit d4faad8

File tree

1 file changed

+19
-12
lines changed

1 file changed

+19
-12
lines changed

llvm/docs/GitHub.rst

Lines changed: 19 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -254,16 +254,6 @@ To illustrate, assume that you are working on two branches in your fork of the
254254

255255
Your options are as follows:
256256

257-
#. Two PRs with a dependency note
258-
259-
Create PR_1 for `feature_1` and PR_2 for `feature_2`. In PR_2, include a
260-
note in the PR summary indicating that it depends on PR_1 (e.g.,
261-
“Depends on #PR_1”).
262-
263-
To make review easier, make it clear which commits are part of the base PR
264-
and which are new, e.g. "The first N commits are from the base PR". This
265-
helps reviewers focus only on the incremental changes.
266-
267257
#. Use user branches in ``llvm/llvm-project``
268258

269259
Create user branches in the main repository, as described
@@ -274,8 +264,25 @@ Your options are as follows:
274264

275265
This approach allows GitHub to display clean, incremental diffs for each PR
276266
in the stack, making it much easier for reviewers to see what has changed at
277-
each step. Once `feature_1` is merged, you can rebase and re-target
278-
`feature_2` to `main`.
267+
each step. Once `feature_1` is merged, GitHub would automatically rebase and
268+
re-target your branch `feature_2` to `main`. For more complex stacks, you can
269+
perform this step using the web interface.
270+
271+
This approach requires
272+
`Commit Access <https://llvm.org/docs/DeveloperPolicy.html#obtaining-commit-access>`_
273+
. However, if you are involved with a Stacked PR, there's a good chance you'll
274+
be granted access.
275+
276+
#. Two PRs with a dependency note
277+
278+
Create PR_1 for `feature_1` and PR_2 for `feature_2`. In PR_2, include a
279+
note in the PR summary indicating that it depends on PR_1 (e.g.,
280+
“Depends on #PR_1”).
281+
282+
The disadvantage of this approach is that GitHub will not show a clean diff.
283+
To make review easier, make it clear which commits are part of the base PR
284+
and which are new, e.g. "The first N commits are from the base PR". This
285+
helps reviewers focus only on the incremental changes.
279286

280287
#. Use a stacked PR tool
281288

0 commit comments

Comments
 (0)