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

[Simon Tatham via llvm-commits]

================
@@ -29,8 +31,48 @@ 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. 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
+
+  Use a tool like SPR or Graphite (described below) to manage stacked PRs more
+  easily.
+
+Each of these approaches can help streamline the review process. Choose the one
----------------
statham-arm wrote:

I think, more than that, perhaps explain why anyone wants to stack multiple PRs in the first place! If you open the whole section by saying "Github doesn't support them" then you assume that people already knew that they wanted them (not to mention what they are).

This certainly wasn't obvious to me. To my way of thinking, one of the _good_ things about a Github PR compared to a Phabricator patch is that a PR doesn't have a 1–1 correspondence between patches and reviews. If you have a patch series containing logically separate sub-changes, the obvious thing is to put it all in a single PR, so that it can be reviewed as a whole, but the logical sub-changes remain separate once it's landed. So if you're coming to LLVM from a Github project that lets you do that (because it doesn't insist on "squash and merge"), you wouldn't think of stacked PRs in the first place.

So perhaps it's worth starting off with some introductory text that explains
1. that we use "squash and merge", so you _can't_ do the more obvious thing you might be used to from elsewhere
2. why we do that (I'm not sure myself but I think it probably has to do with using the multiple commits in the PR to show the evolution of the patch as review progresses)
3. that therefore, if you do want to keep your logical sub-changes separate, you're going to have to put each one in its own PR and stack them in some way, and here are some ways to do it.

https://github.com/llvm/llvm-project/pull/132424