[llvm] [llvm][docs] Extend docs on GitHub's "squash and merge" (PR #129497)
Andrzej Warzyński via llvm-commits
llvm-commits at lists.llvm.org
Wed Mar 5 01:40:56 PST 2025
https://github.com/banach-space updated https://github.com/llvm/llvm-project/pull/129497
>From 0348beedad40a858370b7073b5c4065c061ef85e Mon Sep 17 00:00:00 2001
From: Andrzej Warzynski <andrzej.warzynski at arm.com>
Date: Mon, 3 Mar 2025 08:46:25 +0000
Subject: [PATCH 1/4] [llvm][docs][nfc] Add a note on GitHub's "squash and
merge"
>From what I can tell, many people are still unaware that in LLVM we use
the PR summary (rather than PR commit messages) as the message for the
final commit to be merged. This is particularly unclear to folks without
commit access (folks with commit access can edit the commit message just
before merging).
---
llvm/docs/GitHub.rst | 7 +++++++
1 file changed, 7 insertions(+)
diff --git a/llvm/docs/GitHub.rst b/llvm/docs/GitHub.rst
index 979b87c8d02f6..be230b956e2c6 100644
--- a/llvm/docs/GitHub.rst
+++ b/llvm/docs/GitHub.rst
@@ -214,6 +214,13 @@ 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.
+.. note::
+ When using `Squash and merge` in LLVM’s GitHub web interface, GitHub will
+ use the pull request title and description as the commit message. Only
+ users with commit access can edit the commit message just before merging a PR.
+
+ If you do not have write permissions, make sure the PR title and description
+ are **up to date** before the review process concludes.
Pre-merge Continuous Integration (CI)
-------------------------------------
>From cd0ceb088ddee463da7bcf782391bfa1250a9471 Mon Sep 17 00:00:00 2001
From: Andrzej Warzynski <andrzej.warzynski at arm.com>
Date: Tue, 4 Mar 2025 16:32:47 +0000
Subject: [PATCH 2/4] fixup! [llvm][docs][nfc] Add a note on GitHub's "squash
and merge"
Expand as per David's suggestions
---
llvm/docs/Contributing.rst | 18 ++++++++----------
llvm/docs/GitHub.rst | 28 +++++++++++++++++++++-------
2 files changed, 29 insertions(+), 17 deletions(-)
diff --git a/llvm/docs/Contributing.rst b/llvm/docs/Contributing.rst
index 5ee07fcec5bf9..ae98df1035ec1 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 :doc:`landing-your-change` 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 be230b956e2c6..5a0e42451b4a8 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,6 +150,7 @@ 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:
Landing your change
-------------------
@@ -215,12 +222,19 @@ commonly used first:
this result correctly with a note that a force push did occur.
.. note::
- When using `Squash and merge` in LLVM’s GitHub web interface, GitHub will
- use the pull request title and description as the commit message. Only
- users with commit access can edit the commit message just before merging a PR.
+ 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 commit 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.
- If you do not have write permissions, make sure the PR title and description
- are **up to date** before the review process concludes.
+ In practice, PR summaries often become commit messages. Ensure that the PR
+ title and description are up to date, free of typos, and clearly written —
+ especially if you do not have write permissions and require someone else to
+ merge your PR.
Pre-merge Continuous Integration (CI)
-------------------------------------
@@ -445,8 +459,8 @@ Releases
Backporting Fixes to the Release Branches
-----------------------------------------
You can use special comments on issues or pull requests to make backport
-requests for the release branches. To do this, after your pull request has been
-merged:
+requests for the release branches. To do this, after your pull request has
+been merged:
1. Edit "Milestone" at the right side of the isssue or pull request
to say "LLVM X.Y Release"
>From 662cacfd93d77470e40929423a5df972d4502271 Mon Sep 17 00:00:00 2001
From: Andrzej Warzynski <andrzej.warzynski at arm.com>
Date: Tue, 4 Mar 2025 17:46:56 +0000
Subject: [PATCH 3/4] fixup! fixup! [llvm][docs][nfc] Add a note on GitHub's
"squash and merge"
Re-organise as per David's suggestions
---
llvm/docs/GitHub.rst | 44 ++++++++++++++++++++++----------------------
1 file changed, 22 insertions(+), 22 deletions(-)
diff --git a/llvm/docs/GitHub.rst b/llvm/docs/GitHub.rst
index 5a0e42451b4a8..c35fad6843ad7 100644
--- a/llvm/docs/GitHub.rst
+++ b/llvm/docs/GitHub.rst
@@ -154,12 +154,27 @@ Before merging a PR you must have the required approvals. See
Landing your change
-------------------
-When your PR has been approved you can merge your changes.
+After your PR is approved, ensure that:
-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.
+ * 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`.
+
+.. 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.
@@ -221,21 +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.
-.. 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 commit 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.
-
- In practice, PR summaries often become commit messages. Ensure that the PR
- title and description are up to date, free of typos, and clearly written —
- especially if you do not have write permissions and require someone else to
- merge your PR.
-
Pre-merge Continuous Integration (CI)
-------------------------------------
@@ -459,8 +459,8 @@ Releases
Backporting Fixes to the Release Branches
-----------------------------------------
You can use special comments on issues or pull requests to make backport
-requests for the release branches. To do this, after your pull request has
-been merged:
+requests for the release branches. To do this, after your pull request has been
+merged:
1. Edit "Milestone" at the right side of the isssue or pull request
to say "LLVM X.Y Release"
>From 8ccffbbef8015b8362763788ab8516d77a90b44c Mon Sep 17 00:00:00 2001
From: Andrzej Warzynski <andrzej.warzynski at arm.com>
Date: Wed, 5 Mar 2025 09:40:41 +0000
Subject: [PATCH 4/4] fixup! fixup! fixup! [llvm][docs][nfc] Add a note on
GitHub's "squash and merge"
Add missing empty line
---
llvm/docs/GitHub.rst | 1 +
1 file changed, 1 insertion(+)
diff --git a/llvm/docs/GitHub.rst b/llvm/docs/GitHub.rst
index c35fad6843ad7..2c316d6a2f147 100644
--- a/llvm/docs/GitHub.rst
+++ b/llvm/docs/GitHub.rst
@@ -151,6 +151,7 @@ Before merging a PR you must have the required approvals. See
:ref:`lgtm_how_a_patch_is_accepted` for more details.
.. _landing-your-change:
+
Landing your change
-------------------
More information about the llvm-commits
mailing list