Skip to content

Commit 67f6c6f

Browse files
banach-spacebanach-space
committed
[llvm][docs] Reorder sections in GitHub.rst
Reorder sections in GitHub.rst so that "Branches" and "Stacked Pull Requests" appear after the more general section on pull requests. This improves the conceptual flow for readers new to the process: New order: * Introduction * Before your first PR * Pull Requests * Branches * Stacked Pull Requests * Approvals * Landing your change * ... Previous order: * Introduction * Before your first PR * Branches * Stacked Pull Requests * Pull Requests * Approvals * Landing your change * ... This change only reorders existing text - no content edits.
1 parent 0fc7aec commit 67f6c6f

File tree

1 file changed

+100
-99
lines changed

1 file changed

+100
-99
lines changed

‎llvm/docs/GitHub.rst

Lines changed: 100 additions & 99 deletions
Original file line numberDiff line numberDiff line change
@@ -21,105 +21,6 @@ Before your first PR
2121
Please ensure that you have set a valid email address in your GitHub account,
2222
see :ref:`github-email-address`.
2323

24-
.. _github_branches:
25-
26-
Branches
27-
========
28-
29-
It is possible to create branches that starts with `users/<username>/`, however this is
30-
intended to be able to support "stacked" pull-request. Do not create any branches in the
31-
llvm/llvm-project repository otherwise, please use a fork (see below). User branches that
32-
aren't associated with a pull-request **will be deleted**.
33-
34-
Stacked Pull Requests
35-
=====================
36-
37-
To separate related changes or to break down a larger PR into smaller, reviewable
38-
pieces, use "stacked pull requests" — this helps make the review process
39-
smoother.
40-
41-
.. note::
42-
The LLVM Project monorepo on GitHub is configured to always use "Squash and
43-
Merge" as the pull request merge option. As a result, each PR results in
44-
exactly one commit being merged into the project.
45-
46-
This means that stacked pull requests are the only available option for
47-
landing a series of related changes. In contrast, submitting a PR with
48-
multiple commits and merging them as-is (without squashing) is not supported
49-
in LLVM.
50-
51-
While GitHub does not natively support stacked pull requests, there are several
52-
common alternatives.
53-
54-
To illustrate, assume that you are working on two branches in your fork of the
55-
``llvm/llvm-project`` repository, and you want to eventually merge both into
56-
``main``:
57-
58-
- `feature_1`, which contains commit `feature_commit_1`
59-
- `feature_2`, which contains commit `feature_commit_2` and depends on
60-
`feature_1` (so it also includes `feature_commit_1`)
61-
62-
Your options are as follows:
63-
64-
#. Two PRs with a dependency note
65-
66-
Create PR_1 for `feature_1` and PR_2 for `feature_2`. In PR_2, include a
67-
note in the PR summary indicating that it depends on PR_1 (e.g.,
68-
“Depends on #PR_1”).
69-
70-
To make review easier, make it clear which commits are part of the base PR
71-
and which are new, e.g. "The first N commits are from the base PR". This
72-
helps reviewers focus only on the incremental changes.
73-
74-
#. Use user branches in ``llvm/llvm-project``
75-
76-
Create user branches in the main repository, as described
77-
:ref:`above<github_branches>`. Then:
78-
79-
- Open a pull request from `users/<username>/feature_1` → `main`
80-
- Open another from `users/<username>/feature_2` → `users/<username>/feature_1`
81-
82-
This approach allows GitHub to display clean, incremental diffs for each PR
83-
in the stack, making it much easier for reviewers to see what has changed at
84-
each step. Once `feature_1` is merged, you can rebase and re-target
85-
`feature_2` to `main`.
86-
87-
#. Use a stacked PR tool
88-
89-
Use tools like SPR or Graphite (described below) to automate managing
90-
stacked PRs. These tools are also based on using user branches
91-
in ``llvm/llvm-project``.
92-
93-
.. note::
94-
When not using user branches, GitHub will not display proper diffs for
95-
subsequent PRs in a stack. Instead, it will show a combined diff that
96-
includes all commits from earlier PRs.
97-
98-
As described in the first option above, in such cases it is the PR author’s
99-
responsibility to clearly indicate which commits are relevant to the
100-
current PR. For example: “The first N commits are from the base PR.”
101-
102-
You can avoid this issue by using user branches directly in the
103-
``llvm/llvm-project`` repository.
104-
105-
106-
Using Graphite for stacked Pull Requests
107-
----------------------------------------
108-
109-
`Graphite <https://app.graphite.dev/>`_ is a stacked pull request tool supported
110-
by the LLVM repo (the other being `reviewable.io <https://reviewable.io>`_).
111-
112-
Graphite will want to create branches under ``llvm/llvm-project`` rather than your
113-
private fork, so the guidance above, about branch naming, is critical, otherwise
114-
``gt submit`` (i.e. publish your PRs for review) will fail.
115-
116-
Use ``gt config`` then ``Branch naming settings`` and ``Set a prefix for branch names``.
117-
Include the last ``/``.
118-
119-
If you didn't do the above and Graphite created non-prefixed branches, a simple way to
120-
unblock is to rename (``git -m <old name> <new name>``), and then checkout the branch
121-
and ``gt track``.
122-
12324
Pull Requests
12425
=============
12526
The LLVM project is using GitHub Pull Requests for Code Reviews. This document
@@ -218,6 +119,106 @@ you won't encounter merge conflicts when landing the PR.
218119
collaborating with others on a single branch, be careful how and when you push
219120
changes. ``--force-with-lease`` may be useful in this situation.
220121

122+
.. _github_branches:
123+
124+
Branches
125+
========
126+
127+
It is possible to create branches that start with `users/<username>/`, however this is
128+
intended to be able to support "stacked" pull-request. Do not create any branches in the
129+
llvm/llvm-project repository otherwise, please use a fork (see above). User branches that
130+
aren't associated with a pull-request **will be deleted**.
131+
132+
Stacked Pull Requests
133+
=====================
134+
135+
To separate related changes or to break down a larger PR into smaller, reviewable
136+
pieces, use "stacked pull requests" — this helps make the review process
137+
smoother.
138+
139+
.. note::
140+
The LLVM Project monorepo on GitHub is configured to always use "Squash and
141+
Merge" as the pull request merge option. As a result, each PR results in
142+
exactly one commit being merged into the project.
143+
144+
This means that stacked pull requests are the only available option for
145+
landing a series of related changes. In contrast, submitting a PR with
146+
multiple commits and merging them as-is (without squashing) is not supported
147+
in LLVM.
148+
149+
While GitHub does not natively support stacked pull requests, there are several
150+
common alternatives.
151+
152+
To illustrate, assume that you are working on two branches in your fork of the
153+
``llvm/llvm-project`` repository, and you want to eventually merge both into
154+
``main``:
155+
156+
- `feature_1`, which contains commit `feature_commit_1`
157+
- `feature_2`, which contains commit `feature_commit_2` and depends on
158+
`feature_1` (so it also includes `feature_commit_1`)
159+
160+
Your options are as follows:
161+
162+
#. Two PRs with a dependency note
163+
164+
Create PR_1 for `feature_1` and PR_2 for `feature_2`. In PR_2, include a
165+
note in the PR summary indicating that it depends on PR_1 (e.g.,
166+
“Depends on #PR_1”).
167+
168+
To make review easier, make it clear which commits are part of the base PR
169+
and which are new, e.g. "The first N commits are from the base PR". This
170+
helps reviewers focus only on the incremental changes.
171+
172+
#. Use user branches in ``llvm/llvm-project``
173+
174+
Create user branches in the main repository, as described
175+
:ref:`above<github_branches>`. Then:
176+
177+
- Open a pull request from `users/<username>/feature_1` → `main`
178+
- Open another from `users/<username>/feature_2` → `users/<username>/feature_1`
179+
180+
This approach allows GitHub to display clean, incremental diffs for each PR
181+
in the stack, making it much easier for reviewers to see what has changed at
182+
each step. Once `feature_1` is merged, you can rebase and re-target
183+
`feature_2` to `main`.
184+
185+
#. Use a stacked PR tool
186+
187+
Use tools like SPR or Graphite (described below) to automate managing
188+
stacked PRs. These tools are also based on using user branches
189+
in ``llvm/llvm-project``.
190+
191+
.. note::
192+
When not using user branches, GitHub will not display proper diffs for
193+
subsequent PRs in a stack. Instead, it will show a combined diff that
194+
includes all commits from earlier PRs.
195+
196+
As described in the first option above, in such cases it is the PR author’s
197+
responsibility to clearly indicate which commits are relevant to the
198+
current PR. For example: “The first N commits are from the base PR.”
199+
200+
You can avoid this issue by using user branches directly in the
201+
``llvm/llvm-project`` repository.
202+
203+
204+
Using Graphite for stacked Pull Requests
205+
----------------------------------------
206+
207+
`Graphite <https://app.graphite.dev/>`_ is a stacked pull request tool supported
208+
by the LLVM repo (the other being `reviewable.io <https://reviewable.io>`_).
209+
210+
Graphite will want to create branches under ``llvm/llvm-project`` rather than your
211+
private fork, so the guidance above, about branch naming, is critical, otherwise
212+
``gt submit`` (i.e. publish your PRs for review) will fail.
213+
214+
Use ``gt config`` then ``Branch naming settings`` and ``Set a prefix for branch names``.
215+
Include the last ``/``.
216+
217+
If you didn't do the above and Graphite created non-prefixed branches, a simple way to
218+
unblock is to rename (``git -m <old name> <new name>``), and then checkout the branch
219+
and ``gt track``.
220+
221+
221222
Approvals
222223
---------
223224

0 commit comments

Comments
 (0)