[llvm] [llvm][docs] Reorder sections in GitHub.rst (PR #134212)
Andrzej Warzyński via llvm-commits
llvm-commits at lists.llvm.org
Thu Apr 3 00:23:46 PDT 2025
https://github.com/banach-space created https://github.com/llvm/llvm-project/pull/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
* 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.
>From f930cd9e804fb9b4e94e621e2e5f2ae41a3cca36 Mon Sep 17 00:00:00 2001
From: Andrzej Warzynski <andrzej.warzynski at arm.com>
Date: Thu, 3 Apr 2025 08:17:42 +0100
Subject: [PATCH] [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.
---
llvm/docs/GitHub.rst | 199 ++++++++++++++++++++++---------------------
1 file changed, 100 insertions(+), 99 deletions(-)
diff --git a/llvm/docs/GitHub.rst b/llvm/docs/GitHub.rst
index a235fa51a6473..752cdceb397ad 100644
--- a/llvm/docs/GitHub.rst
+++ b/llvm/docs/GitHub.rst
@@ -21,105 +21,6 @@ Before your first PR
Please ensure that you have set a valid email address in your GitHub account,
see :ref:`github-email-address`.
-.. _github_branches:
-
-Branches
-========
-
-It is possible to create branches that starts with `users/<username>/`, however this is
-intended to be able to support "stacked" pull-request. Do not create any branches in the
-llvm/llvm-project repository otherwise, please use a fork (see below). User branches that
-aren't associated with a pull-request **will be deleted**.
-
-Stacked Pull Requests
-=====================
-
-To separate related changes or to break down a larger PR into smaller, reviewable
-pieces, use "stacked pull requests" — this helps make the review process
-smoother.
-
-.. note::
- The LLVM Project monorepo on GitHub is configured to always use "Squash and
- Merge" as the pull request merge option. As a result, each PR results in
- exactly one commit being merged into the project.
-
- This means that stacked pull requests are the only available option for
- landing a series of related changes. In contrast, submitting a PR with
- multiple commits and merging them as-is (without squashing) is not supported
- in LLVM.
-
-While GitHub does not natively support stacked pull requests, there are several
-common alternatives.
-
-To illustrate, assume that you are working on two branches in your fork of the
-``llvm/llvm-project`` repository, and you want to eventually merge both into
-``main``:
-
-- `feature_1`, which contains commit `feature_commit_1`
-- `feature_2`, which contains commit `feature_commit_2` and depends on
- `feature_1` (so it also includes `feature_commit_1`)
-
-Your options are as follows:
-
-#. Two PRs with a dependency note
-
- Create PR_1 for `feature_1` and PR_2 for `feature_2`. In PR_2, include a
- note in the PR summary indicating that it depends on PR_1 (e.g.,
- “Depends on #PR_1”).
-
- To make review easier, make it clear which commits are part of the base PR
- and which are new, e.g. "The first N commits are from the base PR". This
- helps reviewers focus only on the incremental changes.
-
-#. Use user branches in ``llvm/llvm-project``
-
- Create user branches in the main repository, as described
- :ref:`above<github_branches>`. Then:
-
- - Open a pull request from `users/<username>/feature_1` → `main`
- - Open another from `users/<username>/feature_2` → `users/<username>/feature_1`
-
- This approach allows GitHub to display clean, incremental diffs for each PR
- in the stack, making it much easier for reviewers to see what has changed at
- each step. Once `feature_1` is merged, you can rebase and re-target
- `feature_2` to `main`.
-
-#. Use a stacked PR tool
-
- Use tools like SPR or Graphite (described below) to automate managing
- stacked PRs. These tools are also based on using user branches
- in ``llvm/llvm-project``.
-
-.. note::
- When not using user branches, GitHub will not display proper diffs for
- subsequent PRs in a stack. Instead, it will show a combined diff that
- includes all commits from earlier PRs.
-
- As described in the first option above, in such cases it is the PR author’s
- responsibility to clearly indicate which commits are relevant to the
- current PR. For example: “The first N commits are from the base PR.”
-
- You can avoid this issue by using user branches directly in the
- ``llvm/llvm-project`` repository.
-
-
-Using Graphite for stacked Pull Requests
-----------------------------------------
-
-`Graphite <https://app.graphite.dev/>`_ is a stacked pull request tool supported
-by the LLVM repo (the other being `reviewable.io <https://reviewable.io>`_).
-
-Graphite will want to create branches under ``llvm/llvm-project`` rather than your
-private fork, so the guidance above, about branch naming, is critical, otherwise
-``gt submit`` (i.e. publish your PRs for review) will fail.
-
-Use ``gt config`` then ``Branch naming settings`` and ``Set a prefix for branch names``.
-Include the last ``/``.
-
-If you didn't do the above and Graphite created non-prefixed branches, a simple way to
-unblock is to rename (``git -m <old name> <new name>``), and then checkout the branch
-and ``gt track``.
-
Pull Requests
=============
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.
collaborating with others on a single branch, be careful how and when you push
changes. ``--force-with-lease`` may be useful in this situation.
+.. _github_branches:
+
+Branches
+========
+
+It is possible to create branches that start with `users/<username>/`, however this is
+intended to be able to support "stacked" pull-request. Do not create any branches in the
+llvm/llvm-project repository otherwise, please use a fork (see above). User branches that
+aren't associated with a pull-request **will be deleted**.
+
+Stacked Pull Requests
+=====================
+
+To separate related changes or to break down a larger PR into smaller, reviewable
+pieces, use "stacked pull requests" — this helps make the review process
+smoother.
+
+.. note::
+ The LLVM Project monorepo on GitHub is configured to always use "Squash and
+ Merge" as the pull request merge option. As a result, each PR results in
+ exactly one commit being merged into the project.
+
+ This means that stacked pull requests are the only available option for
+ landing a series of related changes. In contrast, submitting a PR with
+ multiple commits and merging them as-is (without squashing) is not supported
+ in LLVM.
+
+While GitHub does not natively support stacked pull requests, there are several
+common alternatives.
+
+To illustrate, assume that you are working on two branches in your fork of the
+``llvm/llvm-project`` repository, and you want to eventually merge both into
+``main``:
+
+- `feature_1`, which contains commit `feature_commit_1`
+- `feature_2`, which contains commit `feature_commit_2` and depends on
+ `feature_1` (so it also includes `feature_commit_1`)
+
+Your options are as follows:
+
+#. Two PRs with a dependency note
+
+ Create PR_1 for `feature_1` and PR_2 for `feature_2`. In PR_2, include a
+ note in the PR summary indicating that it depends on PR_1 (e.g.,
+ “Depends on #PR_1”).
+
+ To make review easier, make it clear which commits are part of the base PR
+ and which are new, e.g. "The first N commits are from the base PR". This
+ helps reviewers focus only on the incremental changes.
+
+#. Use user branches in ``llvm/llvm-project``
+
+ Create user branches in the main repository, as described
+ :ref:`above<github_branches>`. Then:
+
+ - Open a pull request from `users/<username>/feature_1` → `main`
+ - Open another from `users/<username>/feature_2` → `users/<username>/feature_1`
+
+ This approach allows GitHub to display clean, incremental diffs for each PR
+ in the stack, making it much easier for reviewers to see what has changed at
+ each step. Once `feature_1` is merged, you can rebase and re-target
+ `feature_2` to `main`.
+
+#. Use a stacked PR tool
+
+ Use tools like SPR or Graphite (described below) to automate managing
+ stacked PRs. These tools are also based on using user branches
+ in ``llvm/llvm-project``.
+
+.. note::
+ When not using user branches, GitHub will not display proper diffs for
+ subsequent PRs in a stack. Instead, it will show a combined diff that
+ includes all commits from earlier PRs.
+
+ As described in the first option above, in such cases it is the PR author’s
+ responsibility to clearly indicate which commits are relevant to the
+ current PR. For example: “The first N commits are from the base PR.”
+
+ You can avoid this issue by using user branches directly in the
+ ``llvm/llvm-project`` repository.
+
+
+Using Graphite for stacked Pull Requests
+----------------------------------------
+
+`Graphite <https://app.graphite.dev/>`_ is a stacked pull request tool supported
+by the LLVM repo (the other being `reviewable.io <https://reviewable.io>`_).
+
+Graphite will want to create branches under ``llvm/llvm-project`` rather than your
+private fork, so the guidance above, about branch naming, is critical, otherwise
+``gt submit`` (i.e. publish your PRs for review) will fail.
+
+Use ``gt config`` then ``Branch naming settings`` and ``Set a prefix for branch names``.
+Include the last ``/``.
+
+If you didn't do the above and Graphite created non-prefixed branches, a simple way to
+unblock is to rename (``git -m <old name> <new name>``), and then checkout the branch
+and ``gt track``.
+
+
Approvals
---------
More information about the llvm-commits
mailing list