[llvm] 4dc6763 - [doc] added documentation for pre-merge testing

[Christian Kühnel via llvm-commits]

Author: Christian Kühnel
Date: 2021-04-27T16:53:16+02:00
New Revision: 4dc6763289a0496f59af28141fff6133ba322a04

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

LOG: [doc] added documentation for pre-merge testing

fixes https://github.com/google/llvm-premerge-checks/issues/275

Differential Revision: https://reviews.llvm.org/D100936

Added: 
    llvm/docs/Phabricator_premerge_results.png
    llvm/docs/Phabricator_premerge_unit_tests.png

Modified: 
    llvm/docs/Phabricator.rst

Removed: 
    


################################################################################
diff  --git a/llvm/docs/Phabricator.rst b/llvm/docs/Phabricator.rst
index cbc7c34eab68..6e82a86c65be 100644
--- a/llvm/docs/Phabricator.rst
+++ b/llvm/docs/Phabricator.rst
@@ -158,6 +158,53 @@ when a review changes state, for example by clicking "Accept Revision" in
 the web interface. Thus, please type LGTM into the comment box to accept
 a change from Phabricator.
 
+.. _pre-merge-testing:
+
+Pre-merge testing
+-----------------
+
+The pre-merge tests are a continuous integration (CI) workflow. The workflow 
+checks the patches uploaded to Phabricator before a user merges them to the main 
+branch - thus the term *pre-merge testing*. 
+
+When a user uploads a patch to Phabricator, Phabricator triggers the checks and
+then displays the results. This way bugs in a patch are contained during the 
+code review stage and do not pollute the main branch. 
+
+If you notice issues or have an idea on how to improve pre-merge checks, please 
+`create a new issue <https://github.com/google/llvm-premerge-checks/issues/new>`_ 
+or give a ❤️ to an existing one.
+
+Requirements
+^^^^^^^^^^^^
+
+To get a patch on Phabricator tested, the build server must be able to apply the
+patch to the checked out git repository. Please make sure that either:
+
+* You set a git hash as ``sourceControlBaseRevision`` in Phabricator which is
+  available on the GitHub repository, 
+* **or** you define the dependencies of your patch in Phabricator, 
+* **or** your patch can be applied to the main branch.
+
+Only then can the build server apply the patch locally and run the builds and
+tests.
+
+Accessing build results
+^^^^^^^^^^^^^^^^^^^^^^^
+Phabricator will automatically trigger a build for every new patch you upload or
+modify. Phabricator shows the build results at the top of the entry. Clicking on 
+the links (in the red box) will show more details:
+
+  .. image:: Phabricator_premerge_results.png
+
+The CI will compile and run tests, run clang-format and clang-tidy on lines
+changed.
+
+If a unit test failed, this is shown below the build status. You can also expand
+the unit test to see the details:
+
+  .. image:: Phabricator_premerge_unit_tests.png
+
 Committing a change
 -------------------
 

diff  --git a/llvm/docs/Phabricator_premerge_results.png b/llvm/docs/Phabricator_premerge_results.png
new file mode 100644
index 000000000000..ce55f231148b
Binary files /dev/null and b/llvm/docs/Phabricator_premerge_results.png 
diff er

diff  --git a/llvm/docs/Phabricator_premerge_unit_tests.png b/llvm/docs/Phabricator_premerge_unit_tests.png
new file mode 100644
index 000000000000..fc2088550227
Binary files /dev/null and b/llvm/docs/Phabricator_premerge_unit_tests.png 
diff er