[llvm] [docs][GitHub] Document alternative approach to stacked PRs (PR #132424)
Andrzej Warzyński via llvm-commits
llvm-commits at lists.llvm.org
Wed Mar 26 07:32:41 PDT 2025
https://github.com/banach-space updated https://github.com/llvm/llvm-project/pull/132424
>From be8759dff108486851a5e1972499c7849833624b Mon Sep 17 00:00:00 2001
From: Andrzej Warzynski <andrzej.warzynski at arm.com>
Date: Fri, 21 Mar 2025 16:58:14 +0000
Subject: [PATCH 1/4] [docs][GitHub] Document alternative approach to stacked
PRs
---
llvm/docs/GitHub.rst | 17 ++++++++++++++++-
1 file changed, 16 insertions(+), 1 deletion(-)
diff --git a/llvm/docs/GitHub.rst b/llvm/docs/GitHub.rst
index 03cf2251f955e..8b87e47bda2a8 100644
--- a/llvm/docs/GitHub.rst
+++ b/llvm/docs/GitHub.rst
@@ -29,8 +29,23 @@ intended to be able to support "stacked" pull-request. Do not create any branche
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
+=====================
+
+GitHub does not natively support stacked pull requests. There are two common
+alternatives:
+
+ * Add a note in your PR summary indicating that your patch is part of a
+ series or depends on another PR (e.g., “Depends on #123456”). It also helps
+ to highlight which commits belong to other PRs, so reviewers can focus only
+ on the relevant changes.
+ * Use Graphite (described below), a tool that supports stacked PR workflows.
+
+Both approaches help streamline the review process. Choose the one that works
+best for you.
+
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>`_).
>From ba20d0566388c54856e2e078912823fb057ebcec Mon Sep 17 00:00:00 2001
From: Andrzej Warzynski <andrzej.warzynski at arm.com>
Date: Sat, 22 Mar 2025 19:54:29 +0000
Subject: [PATCH 2/4] fixup! [docs][GitHub] Document alternative approach to
stacked PRs
Expand + add a note on SPR
---
llvm/docs/GitHub.rst | 45 +++++++++++++++++++++++++++++++++++---------
1 file changed, 36 insertions(+), 9 deletions(-)
diff --git a/llvm/docs/GitHub.rst b/llvm/docs/GitHub.rst
index 8b87e47bda2a8..09dc7c16a9c38 100644
--- a/llvm/docs/GitHub.rst
+++ b/llvm/docs/GitHub.rst
@@ -21,6 +21,8 @@ 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
========
@@ -32,17 +34,42 @@ aren't associated with a pull-request **will be deleted**.
Stacked Pull Requests
=====================
-GitHub does not natively support stacked pull requests. There are two common
-alternatives:
+GitHub does not natively support stacked pull requests. However, there are
+several common alternatives.
+
+To illustrate, let's assume you're 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 dependency note
+
+ Create PR_1 for branch feature_1 and PR_2 for branch feature_2. In PR_2, add a
+ note in the PR summary indicating that it is part of a series or depends on
+ another PR (e.g., “Depends on #PR_1”). It's also helpful to highlight which
+ commits belong to the base PR, so reviewers can focus on the new changes.
+
+#. User branches in `llvm/llvm-project`
+
+ Create user branches in the main repository, as described
+ :ref:`above<github_branches>`. Then:
+
+ * Create a pull request from `users/<username>/feature_1` → `main`
+ * Create another from `users/<username>/feature_2` →
+ `users/<username>/feature_1` Once `feature_1` is merged, you can update the
+ base of the second PR to target main.
+
+#. Use a stacked PR tool
- * Add a note in your PR summary indicating that your patch is part of a
- series or depends on another PR (e.g., “Depends on #123456”). It also helps
- to highlight which commits belong to other PRs, so reviewers can focus only
- on the relevant changes.
- * Use Graphite (described below), a tool that supports stacked PR workflows.
+ Use a tool like SPR or Graphite (described below) to manage stacked PRs more
+ easily.
-Both approaches help streamline the review process. Choose the one that works
-best for you.
+Each of these approaches can help streamline the review process. Choose the one
+that works best for your workflow.
Using Graphite for stacked Pull Requests
----------------------------------------
>From 41d32b71ea39b12a7c8bd5bd28ecf32c0089d29f Mon Sep 17 00:00:00 2001
From: Andrzej Warzynski <andrzej.warzynski at arm.com>
Date: Tue, 25 Mar 2025 14:05:52 +0000
Subject: [PATCH 3/4] fixup! fixup! [docs][GitHub] Document alternative
approach to stacked PRs
Address comments from Alex and Mehdi
---
llvm/docs/GitHub.rst | 63 ++++++++++++++++++++++++++++----------------
1 file changed, 40 insertions(+), 23 deletions(-)
diff --git a/llvm/docs/GitHub.rst b/llvm/docs/GitHub.rst
index 09dc7c16a9c38..721a899a49808 100644
--- a/llvm/docs/GitHub.rst
+++ b/llvm/docs/GitHub.rst
@@ -34,42 +34,59 @@ aren't associated with a pull-request **will be deleted**.
Stacked Pull Requests
=====================
-GitHub does not natively support stacked pull requests. However, there are
-several common alternatives.
+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. While GitHub does not natively support stacked pull requests, there
+are several common alternatives.
-To illustrate, let's assume you're working on two branches in your fork of the
-``llvm/llvm-project`` repository, and you want to eventually merge both into ``main``:
+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`).
+- `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 dependency note
+#. Two PRs with a dependency note
- Create PR_1 for branch feature_1 and PR_2 for branch feature_2. In PR_2, add a
- note in the PR summary indicating that it is part of a series or depends on
- another PR (e.g., “Depends on #PR_1”). It's also helpful to highlight which
- commits belong to the base PR, so reviewers can focus on the new changes.
+ 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”).
-#. User branches in `llvm/llvm-project`
+ To make review easier, clearly highlight which commits are part of the base
+ PR and which are new. This helps reviewers focus only on the incremental
+ changes.
- Create user branches in the main repository, as described
- :ref:`above<github_branches>`. Then:
+#. Use user branches in ``llvm/llvm-project``
- * Create a pull request from `users/<username>/feature_1` → `main`
- * Create another from `users/<username>/feature_2` →
- `users/<username>/feature_1` Once `feature_1` is merged, you can update the
- base of the second PR to target main.
+ 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’s 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 a tool like SPR or Graphite (described below) to manage stacked PRs more
- easily.
+ 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::
+ Without using user branches, GitHub will not display a proper diff for
+ subsequent PRs in the stack. Instead, it will show a combined diff that
+ includes all commits in the stack. It is the PR author’s responsibility to
+ make it clear which commits are relevant to the current PR.
+
+ You can avoid this issue by using user branches directly in the
+ ``llvm/llvm-project`` repository.
-Each of these approaches can help streamline the review process. Choose the one
-that works best for your workflow.
Using Graphite for stacked Pull Requests
----------------------------------------
>From 5591fe075a182fe2ea977361ddcb373face86289 Mon Sep 17 00:00:00 2001
From: Andrzej Warzynski <andrzej.warzynski at arm.com>
Date: Wed, 26 Mar 2025 14:22:14 +0000
Subject: [PATCH 4/4] fixup! fixup! fixup! [docs][GitHub] Document alternative
approach to stacked PRs
Address comments from David, Martin and Simon.
---
llvm/docs/GitHub.rst | 37 ++++++++++++++++++++++++++-----------
1 file changed, 26 insertions(+), 11 deletions(-)
diff --git a/llvm/docs/GitHub.rst b/llvm/docs/GitHub.rst
index 721a899a49808..a235fa51a6473 100644
--- a/llvm/docs/GitHub.rst
+++ b/llvm/docs/GitHub.rst
@@ -36,8 +36,20 @@ 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. While GitHub does not natively support stacked pull requests, there
-are several common alternatives.
+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
@@ -55,9 +67,9 @@ Your options are as follows:
note in the PR summary indicating that it depends on PR_1 (e.g.,
“Depends on #PR_1”).
- To make review easier, clearly highlight which commits are part of the base
- PR and which are new. This helps reviewers focus only on the incremental
- changes.
+ 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``
@@ -68,8 +80,8 @@ Your options are as follows:
- 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’s changed
- at each step. Once `feature_1` is merged, you can rebase and re-target
+ 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
@@ -79,10 +91,13 @@ Your options are as follows:
in ``llvm/llvm-project``.
.. note::
- Without using user branches, GitHub will not display a proper diff for
- subsequent PRs in the stack. Instead, it will show a combined diff that
- includes all commits in the stack. It is the PR author’s responsibility to
- make it clear which commits are relevant to the current PR.
+ 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.
More information about the llvm-commits
mailing list