[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
----------------
joker-eph wrote:

It does not change anything about merge conflict (if the PR can be merged by Github, there isn't any), not rebasing affect the kind of test you're running locally!
(that said we're having pre-merge CI? It may do the rebase/merge when it runs?)

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