[llvm] [llvm][docs] Clean up the "Landing Your Change" section of the GitHub docs (PR #112869)

[David Spickett via llvm-commits]

https://github.com/DavidSpickett created https://github.com/llvm/llvm-project/pull/112869

* Note up front that the author may not have permissions to use the merge button and should ask a reviewer to do those steps.
* Make it clear that a single commit PR can be landed with a single button click.
* There are in fact 3 ways to land a multi-commit PR.
* Order the ways in increasing amount of overhead for the PR author.
* Put them in bullet point sections so they are visualy separate.

>From d552a7e4178567c0e55bda53c6688980aa59b249 Mon Sep 17 00:00:00 2001
From: David Spickett <david.spickett at linaro.org>
Date: Fri, 18 Oct 2024 10:14:32 +0100
Subject: [PATCH] [llvm][docs] Clean up the "Landing Your Change" section of
 the GitHub docs

* Note up front that the author may not have permissions to use
  the merge button and should ask a reviewer to do those steps.
* Make it clear that a single commit PR can be landed with a single
  button click.
* There are in fact 3 ways to land a multi-commit PR.
* Order the ways in increasing amount of overhead for the PR
  author.
* Put them in bullet point sections so they are visualy separate.
---
 llvm/docs/GitHub.rst | 91 +++++++++++++++++++++++++-------------------
 1 file changed, 51 insertions(+), 40 deletions(-)

diff --git a/llvm/docs/GitHub.rst b/llvm/docs/GitHub.rst
index bf6e915d4458f2..8421e513da43e0 100644
--- a/llvm/docs/GitHub.rst
+++ b/llvm/docs/GitHub.rst
@@ -135,62 +135,73 @@ you won't encounter merge conflicts when landing the PR.
 
 Landing your change
 -------------------
-When your PR has been accepted you can use the web interface to land your change.
-If you have created multiple commits to address feedback at this point you need
-to consolidate those commits into one commit. There are two different ways to
-do this:
 
-`Interactive rebase <https://git-scm.com/docs/git-rebase#_interactive_mode>`_
-with fixup's. This is the recommended method since you can control the final
-commit message and inspect that the final commit looks as you expect. When
-your local state is correct, remember to force-push to your branch and press
-the merge button afterwards.
+When your PR has been accepted you can merge your changes.
 
-Use the button `Squash and merge` in GitHub's web interface, if you do this
-remember to review the commit message when prompted.
+If you do not have write permissions for the repository, the merge button in
+GitHub's web interface will be disabled. If this is the case, continue following
+the steps here but ask one of your reviewers to click the merge button on your
+behalf.
 
-Afterwards you can select the option `Delete branch` to delete the branch
-from your fork.
+If the PR is a single commit, all you need to do is click the merge button in
+GitHub's web interface.
 
-You can also merge via the CLI by switching to your branch locally and run:
+If your PR contains multiple commits, you need to consolidate those commits into
+one commit. There are three different ways to do this, shown here with the most
+commonly used first:
 
-::
+* Use the button `Squash and merge` in GitHub's web interface, if you do this
+  remember to review the commit message when prompted.
 
-  gh pr merge --squash --delete-branch
+  Afterwards you can select the option `Delete branch` to delete the branch
+  from your fork.
 
-If you observe an error message from the above informing you that your pull
-request is not mergeable, then that is likely because upstream has been
-modified since your pull request was authored in a way that now results in a
-merge conflict. You must first resolve this merge conflict in order to merge
-your pull request. In order to do that:
+* `Interactive rebase <https://git-scm.com/docs/git-rebase#_interactive_mode>`_
+  with fixups. This is the recommended method since you can control the final
+  commit message and check that the final commit looks as you expect. When
+  your local state is correct, remember to force-push to your branch and press
+  the merge button in GitHub's web interface afterwards.
 
-::
+* Merge using the GitHub command line interface. Switch to your branch locally
+  and run:
 
-  git fetch upstream
-  git rebase upstream/main
+  ::
 
-Then fix the source files causing merge conflicts and make sure to rebuild and
-retest the result. Then:
+    gh pr merge --squash --delete-branch
 
-::
+  If you observe an error message from the above informing you that your pull
+  request is not mergeable, then that is likely because upstream has been
+  modified since your pull request was authored in a way that now results in a
+  merge conflict. You must first resolve this merge conflict in order to merge
+  your pull request. In order to do that:
 
-  git add <files with resolved merge conflicts>
-  git rebase --continue
+  ::
 
-Finally, you'll need to force push to your branch one more time before you can
-merge:
+    git fetch upstream
+    git rebase upstream/main
 
-::
+  Then fix the source files causing merge conflicts and make sure to rebuild and
+  retest the result. Then:
 
-  git push -f
-  gh pr merge --squash --delete-branch
+  ::
+
+    git add <files with resolved merge conflicts>
+    git rebase --continue
+
+  Finally, you'll need to force push to your branch one more time before you can
+  merge:
+
+  ::
+
+    git push -f
+    gh pr merge --squash --delete-branch
 
-This force push may ask if you intend to push hundreds, or potentially
-thousands of patches (depending on how long it's been since your pull request
-was initially authored vs. when you intended to merge it). Since you're pushing
-to a branch in your fork, this is ok and expected. Github's UI for the pull
-request will understand that you're rebasing just your patches, and display
-this result correctly with a note that a force push did occur.
+  This force push may ask if you intend to push hundreds, or potentially
+  thousands of patches (depending on how long it's been since your pull request
+  was initially authored vs. when you intended to merge it). Since you're pushing
+  to a branch in your fork, this is ok and expected. Github's UI for the pull
+  request will understand that you're rebasing just your patches, and display
+  this result correctly with a note that a force push did occur.
 
 
 Problems After Landing Your Change