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

[Mehdi Amini via llvm-commits]

================
@@ -21,36 +24,194 @@ 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>`_
+----------------------
+Keep in mind that each pull request should generally only contain one commit.
+This makes it easier for reviewers to understand the introduced changes and
+provide feedback. It also helps maintain a clear and organized commit history
+for the project. If you have multiple changes you want to introduce, it's
+recommended to create separate pull requests for each change.
+
+Create a local branch per commit you want to submit and then push that 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.
----------------
joker-eph wrote:

Ping on this @tra : I'm happy to help addressing post-review comment, but here I don't know why we have this?

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