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

Tue Mar 19 23:35:23 PDT 2024

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

>From 117da67c298ffbc73c472c04aa3f4cf87c5cf030 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 1/5] [Doc] Add a section on CI to the GitHub documentation

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

diff --git a/llvm/docs/Contributing.rst b/llvm/docs/Contributing.rst
index dc8be93463cec1..eef7fc2d363d81 100644
--- a/llvm/docs/Contributing.rst
+++ b/llvm/docs/Contributing.rst
@@ -124,12 +124,24 @@ 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 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-requests 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..26eed27542a39d 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 applied 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 messages 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
 ==================================
 

>From 3051a7b075bc7342fa4755dd3ef6a751bef5240c Mon Sep 17 00:00:00 2001
From: Mehdi Amini <joker.eph at gmail.com>
Date: Fri, 15 Mar 2024 16:47:41 -0700
Subject: [PATCH 2/5] Update llvm/docs/GitHub.rst

Co-authored-by: Renato Golin <rengolin at systemcall.eu>
---
 llvm/docs/GitHub.rst | 1 +
 1 file changed, 1 insertion(+)

diff --git a/llvm/docs/GitHub.rst b/llvm/docs/GitHub.rst
index 26eed27542a39d..4a367cb8ffc59b 100644
--- a/llvm/docs/GitHub.rst
+++ b/llvm/docs/GitHub.rst
@@ -193,6 +193,7 @@ The infrastructure can print messages that make it seem like these are mandatory
 but this is just an artifact of GitHub infrastructure and not a policy of the
 project.
 
+However, please make sure you do not force-merge any changes that have clear test failures directly linked to your changes. Our policy is still to keep the `main` branch in a good condition, and introducing failures to be fixed later violates that policy.
 
 Problems After Landing Your Change
 ==================================

>From 5fad32a71f2b04bdcfe392944f7d63541555c56f Mon Sep 17 00:00:00 2001
From: Mehdi Amini <joker.eph at gmail.com>
Date: Mon, 18 Mar 2024 10:31:43 -0700
Subject: [PATCH 3/5] Update following Renato's comment

---
 llvm/docs/Contributing.rst | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/llvm/docs/Contributing.rst b/llvm/docs/Contributing.rst
index eef7fc2d363d81..a71da60c08ce19 100644
--- a/llvm/docs/Contributing.rst
+++ b/llvm/docs/Contributing.rst
@@ -139,9 +139,9 @@ GitHub will display a message that looks like:
   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-requests with failing CI. We can't disable it for people
-pushing on the command-line.
+This can seem scary, but this is just an artifact of the GitHub setup: it is
+intended as a warning for people merging pull-requests 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.
 

>From 578a4902742507fe3d2daf6928b4036fcf5f848b Mon Sep 17 00:00:00 2001
From: Mehdi Amini <joker.eph at gmail.com>
Date: Tue, 19 Mar 2024 23:35:11 -0700
Subject: [PATCH 4/5] Update llvm/docs/Contributing.rst

Co-authored-by: Nikita Popov <github at npopov.com>
---
 llvm/docs/Contributing.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/llvm/docs/Contributing.rst b/llvm/docs/Contributing.rst
index a71da60c08ce19..344e13d8a70647 100644
--- a/llvm/docs/Contributing.rst
+++ b/llvm/docs/Contributing.rst
@@ -126,7 +126,7 @@ 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.
 
-When pushing directly from the command-line to the `main`` branch, you will need
+When pushing directly from the command-line to the ``main`` branch, you will need
 to rebase your change. LLVM 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.

>From 95a54833f0ed9dd96a5169d4ea2044ad9cf91361 Mon Sep 17 00:00:00 2001
From: Mehdi Amini <joker.eph at gmail.com>
Date: Tue, 19 Mar 2024 23:35:16 -0700
Subject: [PATCH 5/5] Update llvm/docs/Contributing.rst

Co-authored-by: Nikita Popov <github at npopov.com>
---
 llvm/docs/Contributing.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/llvm/docs/Contributing.rst b/llvm/docs/Contributing.rst
index 344e13d8a70647..23f64a6709b626 100644
--- a/llvm/docs/Contributing.rst
+++ b/llvm/docs/Contributing.rst
@@ -128,7 +128,7 @@ GitHub web interface.
 
 When pushing directly from the command-line to the ``main`` branch, you will need
 to rebase your change. LLVM has a linear-history policy, which means
-that merge commits are not allowed and the `main` branch is configured to reject
+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:

