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

[Martin Storsjö 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
----------------
mstorsjo wrote:

@statham-arm AFAIK the reason for mandating "squash and merge" comes from the issue, that github is (supposedly) 1) bad at showing what has changed between one iteration of a PR and the next, if you squash/rebase your commits during review, and 2) bad at keeping inline comments visible and in sync with the surrounding code, during reviews, if you squash/rebase your commits during review. This requires doing PR updates by incremental commits on top, and hence mandating "squash and merge".

Whether it really is so bad at these things to warrant all this extra complexity, is definitely a topic worth bringing up for discussion somewhere - I totally agree with your sentiment here.

(If we could assume that people with merge privileges are git-savvy enough to look at a PR and determine if it is a set of multiple independent commits that should be kept as is, merged via "rebase and merge", or if it is a series of incremental tweaks on what's supposed to be one change and should be squashed - then we could consider to allow both merge styles. But I guess that may be asking a bit much, and creates a pretty big risk for ugly broken intermediate commits ending up in the repo.)

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