[doc] added documentation for pre-merge testing

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

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

diff --git a/llvm/docs/Phabricator.rst b/llvm/docs/Phabricator.rst
index cbc7c34..6e82a86 100644 (file)
--- 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 (file)
index 0000000..ce55f23
Binary files /dev/null and b/llvm/docs/Phabricator_premerge_results.png differ

diff --git a/llvm/docs/Phabricator_premerge_unit_tests.png b/llvm/docs/Phabricator_premerge_unit_tests.png
new file mode 100644 (file)
index 0000000..fc20885
Binary files /dev/null and b/llvm/docs/Phabricator_premerge_unit_tests.png differ