[llvm] [docs][GitHub] Document alternative approach to stacked PRs (PR #132424)

[Andrzej Warzyński via llvm-commits]

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/2] [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/2] 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
 ----------------------------------------