[llvm] [llvm][docs] Reorder Stacked PR approaches in GitHub.rst (PR #138126)

[Paschalis Mpeis via llvm-commits]

https://github.com/paschalis-mpeis updated https://github.com/llvm/llvm-project/pull/138126

>From d4faad85c3c399468a490d8c81f755aae089d7c6 Mon Sep 17 00:00:00 2001
From: Paschalis Mpeis <Paschalis.Mpeis at arm.com>
Date: Thu, 1 May 2025 12:48:54 +0100
Subject: [PATCH 1/3] [llvm][docs] Reorder Stacked PR approaches in GitHub.rst

The 'user branches' approach now appears before the 'dependency note'
approach, as it makes reviewing easier.

Add notes on requiring commit access for the former and on
the disadvantage of the latter.
---
 llvm/docs/GitHub.rst | 31 +++++++++++++++++++------------
 1 file changed, 19 insertions(+), 12 deletions(-)

diff --git a/llvm/docs/GitHub.rst b/llvm/docs/GitHub.rst
index d2652f7d94bd6..b6661595fa433 100644
--- a/llvm/docs/GitHub.rst
+++ b/llvm/docs/GitHub.rst
@@ -254,16 +254,6 @@ To illustrate, assume that you are working on two branches in your fork of the
 
 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
@@ -274,8 +264,25 @@ Your options are as follows:
 
    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`.
+   each step. Once `feature_1` is merged, GitHub would automatically rebase and
+   re-target your branch `feature_2` to `main`. For more complex stacks, you can
+   perform this step using the web interface.
+
+   This approach requires
+   `Commit Access <https://llvm.org/docs/DeveloperPolicy.html#obtaining-commit-access>`_
+   . However, if you are involved with a Stacked PR, there's a good chance you'll
+   be granted access.
+
+#. 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”).
+
+   The disadvantage of this approach is that GitHub will not show a clean diff.
+   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 a stacked PR tool
 

>From 071536af64c8875aae63a3c22e4643ad84e40034 Mon Sep 17 00:00:00 2001
From: Paschalis Mpeis <Paschalis.Mpeis at arm.com>
Date: Fri, 2 May 2025 10:01:25 +0100
Subject: [PATCH 2/3] Addressed reviewers + nit

nit: Removed a space before a dot at the 'Commit Access' link.
---
 llvm/docs/GitHub.rst | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/llvm/docs/GitHub.rst b/llvm/docs/GitHub.rst
index b6661595fa433..a2df0d6bbb761 100644
--- a/llvm/docs/GitHub.rst
+++ b/llvm/docs/GitHub.rst
@@ -264,13 +264,13 @@ Your options are as follows:
 
    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, GitHub would automatically rebase and
+   each step. Once `feature_1` is merged, GitHub will automatically rebase and
    re-target your branch `feature_2` to `main`. For more complex stacks, you can
    perform this step using the web interface.
 
    This approach requires
-   `Commit Access <https://llvm.org/docs/DeveloperPolicy.html#obtaining-commit-access>`_
-   . However, if you are involved with a Stacked PR, there's a good chance you'll
+   `Commit Access <https://llvm.org/docs/DeveloperPolicy.html#obtaining-commit-access>`_.
+   However, if you are involved with a Stacked PR, there's a good chance you'll
    be granted access.
 
 #. Two PRs with a dependency note
@@ -279,7 +279,6 @@ Your options are as follows:
    note in the PR summary indicating that it depends on PR_1 (e.g.,
    “Depends on #PR_1”).
 
-   The disadvantage of this approach is that GitHub will not show a clean diff.
    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.

>From c0b23f97c734ad3e7cb9e016177e775de198330b Mon Sep 17 00:00:00 2001
From: Paschalis Mpeis <Paschalis.Mpeis at arm.com>
Date: Fri, 2 May 2025 14:11:30 +0100
Subject: [PATCH 3/3] Addressing reviewers (2)

---
 llvm/docs/GitHub.rst | 6 ++----
 1 file changed, 2 insertions(+), 4 deletions(-)

diff --git a/llvm/docs/GitHub.rst b/llvm/docs/GitHub.rst
index a2df0d6bbb761..de0022e518cc8 100644
--- a/llvm/docs/GitHub.rst
+++ b/llvm/docs/GitHub.rst
@@ -268,10 +268,8 @@ Your options are as follows:
    re-target your branch `feature_2` to `main`. For more complex stacks, you can
    perform this step using the web interface.
 
-   This approach requires
-   `Commit Access <https://llvm.org/docs/DeveloperPolicy.html#obtaining-commit-access>`_.
-   However, if you are involved with a Stacked PR, there's a good chance you'll
-   be granted access.
+   This approach requires commit access. See how to obtain it
+   `here <https://llvm.org/docs/DeveloperPolicy.html#obtaining-commit-access>`_.
 
 #. Two PRs with a dependency note