[llvm] [Docs][Github] explain how to rectify gh pr merge failure (PR #66223)

[Nick Desaulniers via llvm-commits]

https://github.com/nickdesaulniers updated https://github.com/llvm/llvm-project/pull/66223:

>From a559dd6a64ff8a40d2252944e5eadae237d81c3e Mon Sep 17 00:00:00 2001
From: Nick Desaulniers <ndesaulniers at google.com>
Date: Wed, 13 Sep 2023 08:53:57 -0700
Subject: [PATCH 1/3] [Docs][Github] explain how to rectify gh pr merge failure

I recently went to merge a PR that had a merge conflict:

    $ gh pr merge --squash --delete-branch
    X Pull request #66003 is not mergeable: the merge commit cannot be cleanly created.
    To have the pull request merged after all the requirements have been met, add the `--auto` flag.
    Run the following to resolve the merge conflicts locally:
      gh pr checkout 66003 && git fetch origin main && git merge origin/main

This is how I resolved it; we should recommend this explicitly for
fellow contributors.
---
 llvm/docs/GitHub.rst | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/llvm/docs/GitHub.rst b/llvm/docs/GitHub.rst
index d726c76e7d5f2d4..7b548056deccf5a 100644
--- a/llvm/docs/GitHub.rst
+++ b/llvm/docs/GitHub.rst
@@ -131,6 +131,33 @@ You can also merge via the CLI by switching to your branch locally and run:
 
   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 fetch origin
+  git rebase origin/main
+
+Then fix the source files causing merge conflicts.
+
+::
+
+  git add <files with resolved merge conflicts>
+  <rebuild + retest>
+  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
+
 
 Checking out another PR locally
 -------------------------------

>From b86da6cb1dbdb3932cfa1ec83fe9230831d740b2 Mon Sep 17 00:00:00 2001
From: Nick Desaulniers <ndesaulniers at google.com>
Date: Wed, 13 Sep 2023 09:04:26 -0700
Subject: [PATCH 2/3] add note about force push

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

diff --git a/llvm/docs/GitHub.rst b/llvm/docs/GitHub.rst
index 7b548056deccf5a..9dde0ec8380d57b 100644
--- a/llvm/docs/GitHub.rst
+++ b/llvm/docs/GitHub.rst
@@ -142,12 +142,12 @@ your pull request. In order to do that:
   git fetch origin
   git rebase origin/main
 
-Then fix the source files causing merge conflicts.
+Then fix the source files causing merge conflicts and make sure to rebuild and
+retest the result. Then:
 
 ::
 
   git add <files with resolved merge conflicts>
-  <rebuild + retest>
   git rebase --continue
 
 Finally, you'll need to force push to your branch one more time before you can
@@ -158,6 +158,13 @@ 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.
+
 
 Checking out another PR locally
 -------------------------------

>From ec9e7419fecb2123d48ca49a61d2c3be9e1ba2ee Mon Sep 17 00:00:00 2001
From: Nick Desaulniers <ndesaulniers at google.com>
Date: Wed, 13 Sep 2023 09:05:03 -0700
Subject: [PATCH 3/3] minor typo fix

---
 llvm/docs/GitHub.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/llvm/docs/GitHub.rst b/llvm/docs/GitHub.rst
index 9dde0ec8380d57b..82cb7022af0a6a9 100644
--- a/llvm/docs/GitHub.rst
+++ b/llvm/docs/GitHub.rst
@@ -169,7 +169,7 @@ this result correctly with a note that a force push did occur.
 Checking out another PR locally
 -------------------------------
 Sometimes you want to review another person's PR on your local machine to run
-tests or inspect code in your prefered editor. This is easily done with the
+tests or inspect code in your preferred editor. This is easily done with the
 CLI:
 
 ::