Skip to content

Commit c9157d4

Browse files
banach-spacebanach-space
authored
[llvm][docs] Reorder sections in GitHub.rst (llvm#134212)
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 * Approvals * Landing your change * Branches * Stacked Pull Requests * ... 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 c9157d4

File tree

1 file changed

+102
-99
lines changed

1 file changed

+102
-99
lines changed

‎llvm/docs/GitHub.rst‎

Lines changed: 102 additions & 99 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,9 @@
44
LLVM GitHub User Guide
55
======================
66

7+
.. contents::
8+
:local:
9+
710
Introduction
811
============
912
The LLVM Project uses `GitHub <https://github.com/>`_ for
@@ -21,105 +24,6 @@ Before your first PR
2124
Please ensure that you have set a valid email address in your GitHub account,
2225
see :ref:`github-email-address`.
2326

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-
12327
Pull Requests
12428
=============
12529
The LLVM project is using GitHub Pull Requests for Code Reviews. This document
@@ -310,6 +214,105 @@ commonly used first:
310214
request will understand that you're rebasing just your patches, and display
311215
this result correctly with a note that a force push did occur.
312216

217+
.. _github_branches:
218+
219+
Branches
220+
========
221+
222+
It is possible to create branches that start with `users/<username>/`, however this is
223+
intended to be able to support "stacked" pull-request. Do not create any branches in the
224+
llvm/llvm-project repository otherwise, please use a fork (see above). User branches that
225+
aren't associated with a pull-request **will be deleted**.
226+
227+
Stacked Pull Requests
228+
=====================
229+
230+
To separate related changes or to break down a larger PR into smaller, reviewable
231+
pieces, use "stacked pull requests" — this helps make the review process
232+
smoother.
233+
234+
.. note::
235+
The LLVM Project monorepo on GitHub is configured to always use "Squash and
236+
Merge" as the pull request merge option. As a result, each PR results in
237+
exactly one commit being merged into the project.
238+
239+
This means that stacked pull requests are the only available option for
240+
landing a series of related changes. In contrast, submitting a PR with
241+
multiple commits and merging them as-is (without squashing) is not supported
242+
in LLVM.
243+
244+
While GitHub does not natively support stacked pull requests, there are several
245+
common alternatives.
246+
247+
To illustrate, assume that you are working on two branches in your fork of the
248+
``llvm/llvm-project`` repository, and you want to eventually merge both into
249+
``main``:
250+
251+
- `feature_1`, which contains commit `feature_commit_1`
252+
- `feature_2`, which contains commit `feature_commit_2` and depends on
253+
`feature_1` (so it also includes `feature_commit_1`)
254+
255+
Your options are as follows:
256+
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+
267+
#. Use user branches in ``llvm/llvm-project``
268+
269+
Create user branches in the main repository, as described
270+
:ref:`above<github_branches>`. Then:
271+
272+
- Open a pull request from `users/<username>/feature_1` → `main`
273+
- Open another from `users/<username>/feature_2` → `users/<username>/feature_1`
274+
275+
This approach allows GitHub to display clean, incremental diffs for each PR
276+
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`.
279+
280+
#. Use a stacked PR tool
281+
282+
Use tools like SPR or Graphite (described below) to automate managing
283+
stacked PRs. These tools are also based on using user branches
284+
in ``llvm/llvm-project``.
285+
286+
.. note::
287+
When not using user branches, GitHub will not display proper diffs for
288+
subsequent PRs in a stack. Instead, it will show a combined diff that
289+
includes all commits from earlier PRs.
290+
291+
As described in the first option above, in such cases it is the PR author’s
292+
responsibility to clearly indicate which commits are relevant to the
293+
current PR. For example: “The first N commits are from the base PR.”
294+
295+
You can avoid this issue by using user branches directly in the
296+
``llvm/llvm-project`` repository.
297+
298+
299+
Using Graphite for stacked Pull Requests
300+
----------------------------------------
301+
302+
`Graphite <https://app.graphite.dev/>`_ is a stacked pull request tool supported
303+
by the LLVM repo (the other being `reviewable.io <https://reviewable.io>`_).
304+
305+
Graphite will want to create branches under ``llvm/llvm-project`` rather than your
306+
private fork, so the guidance above, about branch naming, is critical, otherwise
307+
``gt submit`` (i.e. publish your PRs for review) will fail.
308+
309+
Use ``gt config`` then ``Branch naming settings`` and ``Set a prefix for branch names``.
310+
Include the last ``/``.
311+
312+
If you didn't do the above and Graphite created non-prefixed branches, a simple way to
313+
unblock is to rename (``git -m <old name> <new name>``), and then checkout the branch
314+
and ``gt track``.
315+
313316
Pre-merge Continuous Integration (CI)
314317
-------------------------------------
315318

0 commit comments

Comments
 (0)