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

[via llvm-commits]

Author: Mehdi Amini
Date: 2024-12-20T01:28:36+01:00
New Revision: b13592219c421820b7d774dfe360f9f2d9bd94f6

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

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

See
https://discourse.llvm.org/t/rfc-add-a-warning-when-bypassing-the-premerge-testing/77610
for context.

Added: 
    

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

Removed: 
    


################################################################################
diff  --git a/llvm/docs/Contributing.rst b/llvm/docs/Contributing.rst
index 38c05811828642..cf48c66dc0d068 100644
--- a/llvm/docs/Contributing.rst
+++ b/llvm/docs/Contributing.rst
@@ -118,12 +118,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 this:
+
+.. 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 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.
 

diff  --git a/llvm/docs/GitHub.rst b/llvm/docs/GitHub.rst
index 37995969b6df38..85766bfe94afd2 100644
--- a/llvm/docs/GitHub.rst
+++ b/llvm/docs/GitHub.rst
@@ -215,6 +215,28 @@ commonly used first:
   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.
+
+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
 ==================================