[llvm] [Doc] Add a section on CI to the GitHub documentation (PR #85376)

[Mehdi Amini via llvm-commits]

https://github.com/joker-eph created https://github.com/llvm/llvm-project/pull/85376

None

>From d315f43cf7692f5011adb31a8a6c6266571590e9 Mon Sep 17 00:00:00 2001
From: Mehdi Amini <joker.eph at gmail.com>
Date: Fri, 15 Mar 2024 02:44:34 -0700
Subject: [PATCH] [Doc] Add a section on CI to the GitHub documentation

---
 llvm/docs/Contributing.rst | 21 ++++++++++++++++-----
 llvm/docs/GitHub.rst       | 18 ++++++++++++++++++
 2 files changed, 34 insertions(+), 5 deletions(-)

diff --git a/llvm/docs/Contributing.rst b/llvm/docs/Contributing.rst
index dc8be93463cec1..23607f4c2ea62a 100644
--- a/llvm/docs/Contributing.rst
+++ b/llvm/docs/Contributing.rst
@@ -124,12 +124,23 @@ For developers to commit changes from Git
 -----------------------------------------
 
 Once a patch is reviewed, you can select the "Squash and merge" button in the
-GitHub web interface. You might need to rebase your change before pushing
-it to the repo.
+GitHub web interface.
 
-LLVM currently has a linear-history policy, which means that merge commits are
-not allowed. The `llvm-project` repo on github is configured to reject pushes
-that include merges, so the `git rebase` step above is required.
+When pushing directly from the command-line to the `main`` branch, you will need
+to rebase your change. LLVM currently has a linear-history policy, which means
+that merge commits are not allowed and the `main` branch is configured to reject
+pushes that include merges.
+GitHub will display a message that looks like:
+
+.. code-block:: console
+
+  remote: Bypassed rule violations for refs/heads/main:
+  remote:
+  remote: - Required status check “buildkite/github-pull-requests” is expected.
+
+This can seem scary, but you likely did nothing wrong: it is intended as a warning
+for people merging pull-request with failing CI. We can't disable it for people
+pushing on the command-line.
 
 Please ask for help if you're having trouble with your particular git workflow.
 
diff --git a/llvm/docs/GitHub.rst b/llvm/docs/GitHub.rst
index 4010958c5d3133..e663b2af5d7b3c 100644
--- a/llvm/docs/GitHub.rst
+++ b/llvm/docs/GitHub.rst
@@ -176,6 +176,24 @@ 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)
+-------------------------------------
+
+Multiple checks will be applies on a pull-request, either for linting/formatting
+or some build and tests. None of these are perfect and you will encounter
+false positive, infrastructure failures (unstable or unavailable worker), or
+you will be unlucky and based your change on a broken revision of the main branch.
+
+None of the checks are strictly mandatory: these are tools to help us build a
+better codebase and be more productive (by avoiding issues found post-merge and
+possible reverts). As a developer you're empowered to exercise your judgement
+about bypassing any of the checks when merging code.
+
+The infrastructure can print message that make it seem like these are mandatory,
+but this is just an artifact of GitHub infrastructure and not a policy of the
+project.
+
+
 Problems After Landing Your Change
 ==================================