[llvm] [Docs] Update contribution guide to remove the single-commit requirement (PR #212031)

[via llvm-commits]

https://github.com/Sirraide updated https://github.com/llvm/llvm-project/pull/212031

>From 0ed494061775a5b19de6bed842ba341b516e91b3 Mon Sep 17 00:00:00 2001
From: Sirraide <aeternalmail at gmail.com>
Date: Sat, 25 Jul 2026 17:45:51 +0200
Subject: [PATCH 1/4] [Docs] Update contribution guide to remove the
 single-commit requirement

---
 llvm/docs/Contributing.md | 13 ++++++++++---
 1 file changed, 10 insertions(+), 3 deletions(-)

diff --git a/llvm/docs/Contributing.md b/llvm/docs/Contributing.md
index 3dba6cdc22fed..e6586140b723a 100644
--- a/llvm/docs/Contributing.md
+++ b/llvm/docs/Contributing.md
@@ -29,8 +29,10 @@ let people know you are working on it.
 Then try to reproduce and fix the bug with upstream LLVM. Start by building
 LLVM from source as described in {doc}`GettingStarted` and
 use the built binaries to reproduce the failure described in the bug. Use
-a debug build (`-DCMAKE_BUILD_TYPE=Debug`) or a build with assertions
-(`-DLLVM_ENABLE_ASSERTIONS=On`, enabled for Debug builds).
+a build with assertions (`-DLLVM_ENABLE_ASSERTIONS=On`). If you want to build
+LLVM in Debug mode, consider using `LLVM_PARALLEL_LINK_JOBS` and set the linker
+to anything other than GNU `ld` (e.g. `lld` or `mold`); otherwise, you'll likely
+run out of memory unless you have a lot of RAM.
 
 ### Reporting a Security Issue
 
@@ -51,7 +53,12 @@ Once you have a patch ready, it is time to submit it. The patch should:
 * conform to the {doc}`CodingStandards`. You can use the [clang-format-diff.py] or [git-clang-format] tools to automatically format your patch properly.
 * not contain any unrelated changes
 * be an isolated change. Independent changes should be submitted as separate patches as this makes reviewing easier.
-* have a single commit, up-to-date with the upstream `origin/main` branch, and don't have merges.
+
+```{note}
+It's ok for a patch to contain multiple commits; we use the 'Squash and Merge'
+button on GitHub when merging PRs, i.e. all commits will be combined into a
+single one by GitHub at merge time.
+```
 
 (format patches)=
 

>From ffe728cb74521daa803efea98189a830db2105b8 Mon Sep 17 00:00:00 2001
From: Sirraide <aeternalmail at gmail.com>
Date: Mon, 27 Jul 2026 17:35:22 +0200
Subject: [PATCH 2/4] add note about rebasing

---
 llvm/docs/Contributing.md | 12 +++++++++---
 1 file changed, 9 insertions(+), 3 deletions(-)

diff --git a/llvm/docs/Contributing.md b/llvm/docs/Contributing.md
index e6586140b723a..c9d20fd88313b 100644
--- a/llvm/docs/Contributing.md
+++ b/llvm/docs/Contributing.md
@@ -55,9 +55,15 @@ Once you have a patch ready, it is time to submit it. The patch should:
 * be an isolated change. Independent changes should be submitted as separate patches as this makes reviewing easier.
 
 ```{note}
-It's ok for a patch to contain multiple commits; we use the 'Squash and Merge'
-button on GitHub when merging PRs, i.e. all commits will be combined into a
-single one by GitHub at merge time.
+When a PR is accepted and submitted into mainline, all changes from the PR are combined into a single commit using GitHub's "Squash and Merge" button. (We don't use merge commits on LLVM's mainline.) Because of that policy, the series of commits inside a PR branch does not make it into the "permanent record", and is thus not of critical importance.
+
+However, in order to make it easy for reviewers to understand the changes being made during the course of a PR review, it is recommended to follow these guidelines:
+
+- When opening a new PR, prefer to have a single (or small number) of commits on your branch, up-to-date with the upstream `origin/main` branch, and without merges. (This might involve rebasing your local branch prior to creating a PR.)
+
+- Once a PR has been sent for review, prefer to not rebase or modify existing commits already seen by reviewers. Any changes in response to review commits should be added as a new commit on top of the existing ones. If the PR is blocked by merge-conflicts, you should generally resolve the issue by merging main into your PR branch as a separate commit, rather than by rebasing.
+
+Also, be aware that the PR's description/first-comment will be used as the commit message of the final squashed commit. Make sure the PR description contains the message you wish to use, does not contain anything extraneous, and that you update it if the PR evolves during the review. Note: while GitHub copies commit messages into the PR description when initially creating a PR, subsequent messages are ignored; updates must be made directly to the PR description.
 ```
 
 (format patches)=

>From f6dedb535f65e4ec9acb3f1783b9873e64054267 Mon Sep 17 00:00:00 2001
From: Sirraide <aeternalmail at gmail.com>
Date: Tue, 28 Jul 2026 17:56:37 +0200
Subject: [PATCH 3/4] describe some more cmake flags and add link to cmake docs

---
 llvm/docs/Contributing.md | 16 +++++++++++-----
 1 file changed, 11 insertions(+), 5 deletions(-)

diff --git a/llvm/docs/Contributing.md b/llvm/docs/Contributing.md
index c9d20fd88313b..cbb302171ab75 100644
--- a/llvm/docs/Contributing.md
+++ b/llvm/docs/Contributing.md
@@ -28,11 +28,17 @@ let people know you are working on it.
 
 Then try to reproduce and fix the bug with upstream LLVM. Start by building
 LLVM from source as described in {doc}`GettingStarted` and
-use the built binaries to reproduce the failure described in the bug. Use
-a build with assertions (`-DLLVM_ENABLE_ASSERTIONS=On`). If you want to build
-LLVM in Debug mode, consider using `LLVM_PARALLEL_LINK_JOBS` and set the linker
-to anything other than GNU `ld` (e.g. `lld` or `mold`); otherwise, you'll likely
-run out of memory unless you have a lot of RAM.
+use the built binaries to reproduce the failure described in the bug.
+
+Use a Release build (`-DCMAKE_BUILD_TYPE=Release` with assertions (`-DLLVM_ENABLE_ASSERTIONS=On`).
+If you want to build LLVM in Debug mode (`-DCMAKE_BUILD_TYPE=Debug`), consider using
+`LLVM_PARALLEL_LINK_JOBS` and set the linker to anything other than GNU `ld`
+(e.g. `lld` or `mold`, by passing `-DLLVM_USE_LINKER=lld` or `-DLLVM_USE_LINKER=mold`);
+otherwise, you'll likely run out of memory unless you have a lot of RAM.
+
+Irrespective of build type (Release or Debug), you may also want to pass
+`-DLLVM_UNREACHABLE_OPTIMIZE=OFF` to get crash messages from `llvm_unreachable()`.
+See also {doc}`CMake` for more information about how to build LLVM.
 
 ### Reporting a Security Issue
 

>From fefebab1b9d698e8de5256b34a2dd9eb561673cc Mon Sep 17 00:00:00 2001
From: Sirraide <aeternalmail at gmail.com>
Date: Tue, 28 Jul 2026 17:58:44 +0200
Subject: [PATCH 4/4] add -D

---
 llvm/docs/Contributing.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/llvm/docs/Contributing.md b/llvm/docs/Contributing.md
index cbb302171ab75..35757751e0c56 100644
--- a/llvm/docs/Contributing.md
+++ b/llvm/docs/Contributing.md
@@ -32,7 +32,7 @@ use the built binaries to reproduce the failure described in the bug.
 
 Use a Release build (`-DCMAKE_BUILD_TYPE=Release` with assertions (`-DLLVM_ENABLE_ASSERTIONS=On`).
 If you want to build LLVM in Debug mode (`-DCMAKE_BUILD_TYPE=Debug`), consider using
-`LLVM_PARALLEL_LINK_JOBS` and set the linker to anything other than GNU `ld`
+`-DLLVM_PARALLEL_LINK_JOBS=number` and set the linker to anything other than GNU `ld`
 (e.g. `lld` or `mold`, by passing `-DLLVM_USE_LINKER=lld` or `-DLLVM_USE_LINKER=mold`);
 otherwise, you'll likely run out of memory unless you have a lot of RAM.