[llvm] 29ff168 - [llvm][docs] Extend docs on GitHub's "squash and merge" (#129497)

[via llvm-commits]

Author: Andrzej Warzyński
Date: 2025-03-06T12:24:41Z
New Revision: 29ff168363fa9a41f04b19a9afe5930330f35b4c

URL: https://github.com/llvm/llvm-project/commit/29ff168363fa9a41f04b19a9afe5930330f35b4c
DIFF: https://github.com/llvm/llvm-project/commit/29ff168363fa9a41f04b19a9afe5930330f35b4c.diff

LOG: [llvm][docs] Extend docs on GitHub's "squash and merge" (#129497)

>From what I’ve observed, some contributors are still unaware that in LLVM, the
PR summary - not the commit messages - is used as the final commit message when
merging. This is especially unclear to those without commit access, as only
users with commit access can edit the commit message before merging.

This PR clarifies that policy and consolidates all relevant information into
`GitHub.rst`, ensuring it is no longer split between `GitHub.rst` and
`Contributing.rst`.

Note, a big part of this change is merely moving text between the docs.

Added: 
    

Modified: 
    llvm/docs/Contributing.rst
    llvm/docs/GitHub.rst

Removed: 
    


################################################################################
diff  --git a/llvm/docs/Contributing.rst b/llvm/docs/Contributing.rst
index 5ee07fcec5bf9..28b28ffda4290 100644
--- a/llvm/docs/Contributing.rst
+++ b/llvm/docs/Contributing.rst
@@ -129,16 +129,10 @@ review by 'ping'ing the GitHub PR with "Ping" in a comment. The common courtesy
 is once a week. Please remember that you are asking for valuable time from
 other professional developers.
 
-After your PR is approved, ensure that:
-
-  * The PR title and description describe the final changes. These will be used
-    as the title and message of the final squashed commit. The titles and
-    messages of commits in the PR will **not** be used.
-  * You have set a valid email address in your GitHub account, see :ref:`github-email-address`.
-
-Now you can merge your PR. If you do not have the ability to merge the PR, ask your
-reviewers to merge it on your behalf. You must do this explicitly, as reviewers'
-default assumption is that you are able to merge your own PR.
+After your PR is approved, you can merge it. If you do not have the ability to
+merge the PR, ask your reviewers to merge it on your behalf. You must do this
+explicitly, as reviewers' default assumption is that you are able to merge your
+own PR.
 
 For more information on LLVM's code-review process, please see
 :doc:`CodeReview`.
@@ -148,6 +142,10 @@ For more information on LLVM's code-review process, please see
 For developers to commit changes from Git
 -----------------------------------------
 
+.. note::
+   See also :ref:`GitHub <github-reviews>` for more details on merging your changes
+   into LLVM project monorepo.
+
 Once a patch is reviewed, you can select the "Squash and merge" button in the
 GitHub web interface.
 

diff  --git a/llvm/docs/GitHub.rst b/llvm/docs/GitHub.rst
index 979b87c8d02f6..03cf2251f955e 100644
--- a/llvm/docs/GitHub.rst
+++ b/llvm/docs/GitHub.rst
@@ -15,6 +15,12 @@ The LLVM Project uses `GitHub <https://github.com/>`_ for
 This page describes how the LLVM Project users and developers can
 participate in the project using GitHub.
 
+Before your first PR
+====================
+
+Please ensure that you have set a valid email address in your GitHub account,
+see :ref:`github-email-address`.
+
 Branches
 ========
 
@@ -144,15 +150,31 @@ Approvals
 Before merging a PR you must have the required approvals. See
 :ref:`lgtm_how_a_patch_is_accepted` for more details.
 
+
 Landing your change
 -------------------
 
-When your PR has been approved you can merge your changes.
+After your PR is approved, ensure that:
+
+  * The PR title and description describe the final changes. These will be used
+    as the title and message of the final squashed commit. The titles and
+    messages of commits in the PR will **not** be used.
+  * You have set a valid email address in your GitHub account, see :ref:`github-email-address`.
 
-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.
+.. note::
+   The LLVM Project monorepo on GitHub is configured to always use "Squash
+   and Merge" as the pull request merge option when using the web interface.
+   With this option, GitHub uses the PR summary as the default commit
+   message.
+
+   Users with write access who can merge PRs have a final opportunity to edit
+   the commit title and message before merging. However, this option is not
+   available to contributors without write access.
+
+At this point, you can merge your changes. 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.
 
 If the PR is a single commit, all you need to do is click the merge button in
 GitHub's web interface.
@@ -214,7 +236,6 @@ commonly used first:
   request will understand that you're rebasing just your patches, and display
   this result correctly with a note that a force push did occur.
 
-
 Pre-merge Continuous Integration (CI)
 -------------------------------------