[llvm] [Docs] Update documentation for the new GitHub workflow (PR #65162)

Fri Sep 1 11:24:53 PDT 2023

================
@@ -21,36 +24,173 @@ branches being used for "stacked" pull requests will be allowed.
 
 Pull Requests
 =============
-The LLVM Project does not currently accept pull requests for the llvm/llvm-project
-repository.  However, there is a
-`plan <https://discourse.llvm.org/t/code-review-process-update/63964>`_ to move
-to pull requests in the future.  This section documents the pull request
-policies LLVM will be adopting once the project starts using them.
+The LLVM project is using GitHub Pull Requests for Code Reviews. This document
+describes the typical workflow of creating a Pull Request and getting it reviewed
+and accepted. This is meant as an overview of the GitHub workflow, for complete
+documentation refer to `GitHub's documentation <https://docs.github.com/pull-requests>`_.
+
+GitHub Tools
+------------
+You can interact with GitHub in several ways: via git command line tools,
+the web browser, `GitHub Desktop <https://desktop.github.com/>`_, or the
+`GitHub CLI <https://cli.github.com>`_. This guide will cover the git command line
+tools and the GitHub CLI. The GitHub CLI (`gh`) will be most like the `arc` workflow and
+recommended.
 
 Creating Pull Requests
-^^^^^^^^^^^^^^^^^^^^^^
+----------------------
 For pull requests, please push a branch to your
 `fork <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks>`_
 of the llvm-project and
 `create a pull request from the fork <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork>`_.
 
+Creating Pull Requests with GitHub CLI
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+With the CLI it's enough to create the branch locally and then run:
+
+::
+
+  gh pr create
+
+When prompted select to create and use your own fork and follow
+the instructions to add more information needed.
+
+.. note::
+
+  When you let the GitHub CLI create a fork of llvm-project to
+  your user, it will change the git "remotes" so that "origin" points
+  to your fork and "upstream" points to the main llvm-project repository.
+
 Updating Pull Requests
-^^^^^^^^^^^^^^^^^^^^^^
+----------------------
+In order to update your pull request, the only thing you need to do is to push
+your new commits to the branch in your fork. That will automatically update
+the pull request.
+
 When updating a pull request, you should push additional "fix up" commits to
-your branch instead of force pushing.  This makes it easier for GitHub to
-track the context of previous review comments.
+your branch instead of force pushing. This makes it easier for GitHub to
+track the context of previous review comments. Consider using the
+`built-in support for fixups <https://git-scm.com/docs/git-commit#Documentation/git-commit.txt---fixupamendrewordltcommitgt>`_
+in git.
 
-If you do this, you must squash and merge before committing and
+If you do this, you must squash and merge before landing the PR and
 you must use the pull request title and description as the commit message.
-The default commit message for a squashed pull request is the pull request
-description, so this will allow reviewers to review the commit message before
-approving the commit.
+You can do this manually with an interactive git rebase or with GitHub's
+built-in tool. See the section about landing your fix below.
+
+When pushing to your branch, make sure you push to the correct fork. Check your
+remotes with:
+
+::
+
+  git remote -v
+
+And make sure you push to the remote that's pointing to your fork.
+
+Rebasing Pull Requests and Force Pushes
+---------------------------------------
+In general, you should avoid rebasing a Pull Request and force pushing to the
+branch that's the root of the Pull Request during the review. This action will
+make the context of the old changes and comments harder to find and read.
+
+Sometimes, a rebase might be needed to update your branch with a fix for a test
+or in some dependent code.
+
+After your PR is reviewed and accepted, you want to rebase your branch to ensure
+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.
+
+Use the button `Squash and merge` in GitHub's web interface, if you do this
+remember to review the commit message when prompted.
+
+Afterwards you can select the option `Delete branch` to delete the branch
+from your fork.
+
+You can also merge via the CLI by switching to your branch locally and run:
+
+::
+
+  gh pr merge --squash --delete-branch
+
+
+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
+CLI:
+
+::
+
+  gh pr checkout <PR Number>
+
+This is also possible with the web interface and the normal git command line
+tools, but the process is a bit more complicated. See GitHubs
+`documentation <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/checking-out-pull-requests-locally?platform=linux&tool=webui#modifying-an-inactive-pull-request-locally>`_
+on the topic.
+
+Example Pull Request with GitHub CLI
+====================================
+Here is an example for creating a Pull Request with the GitHub CLI:
+
+::
+
+  # Clone the repo
+  gh repo clone llvm/llvm-project
+
+  # Switch to the repo and create a new branch
+  cd llvm-project
+  git switch -c my_change
+
+  # Create your changes
+  $EDITOR file.cpp
+
+  # Don't forget clang-format
+  git clang-format
+
+  # Commit, use a good commit message
+  git commit file.cpp
+
+  # Create the PR, select to use your own fork when prompted.
+  gh pr create
+
+  # If you get any review comments, come back to the branch and
+  # adjust them.
+  git switch my_change
+  $EDITOR file.cpp
+
+  # Commit your changes
+  git commit file.cpp -m "Code Review adjustments"
+
+  # Push your changes to your fork branch, be mindful of
+  # your remotes here, if you don't remember what points to your
+  # fork, use git remote -v to see. Usually origin points to your
+  # fork and upstream to llvm/llvm-project
+  git push origin my_change
+
+  # When your PR is accepted, you can now rebase it and make sure
+  # you have all the latest changes.
+  git rebase -i origin/main
+
+  # Now merge it
+  gh pr merge --squash --delete
----------------
joker-eph wrote:

Does `gh pr merge`  asks interactively about the resulting commit message? I think when I click "squash and merge" in the UI it pops-up and asks.

Our settings should be (hopefully) to use the PR description, but that would mean that amending a commit locally and setting a commit message would be ignored by `gh pr merge` ...

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