[PATCH] D100936: [doc] added documentation for pre-merge testing

[Christian Kühnel via Phabricator via llvm-commits]

kuhnel created this revision.
kuhnel added a reviewer: goncharov.
kuhnel requested review of this revision.
Herald added a project: LLVM.
Herald added a subscriber: llvm-commits.

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


Repository:
  rG LLVM Github Monorepo

https://reviews.llvm.org/D100936

Files:
  llvm/docs/Phabricator.rst
  llvm/docs/Phabricator_premerge_results.png
  llvm/docs/Phabricator_premerge_unit_tests.png


Index: llvm/docs/Phabricator.rst
===================================================================
--- llvm/docs/Phabricator.rst
+++ llvm/docs/Phabricator.rst
@@ -158,6 +158,57 @@
 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
+^^^^^^^^^^^^
+
+Builds are only triggered if the Revision in Phabricator is created/updated
+via ``arc diff``. If you update a Revision via the Web UI it will not trigger a
+build.
+
+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
 -------------------
 


-------------- next part --------------
A non-text attachment was scrubbed...
Name: D100936.339152.patch
Type: text/x-patch
Size: 2297 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20210421/339e5be7/attachment.bin>