Merge topic 'doc-dev-testing'

2927e437 Help/dev: Document the CMake Testing Process
b55e19dd Help/dev: Revise README to have a bullet list of available documents

Acked-by: Kitware Robot <[email protected]>
Acked-by: Ben Boeckel <[email protected]>
Merge-request: !561

Help/dev/README.rst

@@ -19,9 +19,13 @@ Upstream Development
 
 CMake uses `Kitware's GitLab Instance`_ to manage development, review, and
 integration of changes.  The `CMake Repository`_ holds the integration
-branches and tags.  Changes follow the `CMake Review Process`_ for
-integration.
+branches and tags.  Upstream development processes are covered by the
+following documents:
+
+* The `CMake Review Process`_ manages integration of changes.
+* The `CMake Testing Process`_ drives integration testing.
 
 .. _`Kitware's GitLab Instance`: https://gitlab.kitware.com
 .. _`CMake Repository`: https://gitlab.kitware.com/cmake/cmake
 .. _`CMake Review Process`: review.rst
+.. _`CMake Testing Process`: testing.rst

Help/dev/review.rst

@@ -198,14 +198,14 @@ Integration Testing
 
 The above `topic testing`_ tests the MR topic independent of other
 merge requests and on only a few key platforms and configurations.
-CMake also has a large number of testing machines provided by Kitware
-and generous volunteers that cover nearly all supported platforms,
-generators, and configurations.  In order to avoid overwhelming these
-resources, they do not test every MR individually.  Instead, these
-machines follow an *integration branch*, run tests on a nightly basis
-(or continuously during the day), and post to the `CMake CDash Page`_.
-Some follow ``master``.  Most follow a special integration branch,
-the *topic stage*.
+The `CMake Testing Process`_ also has a large number of machines
+provided by Kitware and generous volunteers that cover nearly all
+supported platforms, generators, and configurations.  In order to
+avoid overwhelming these resources, they do not test every MR
+individually.  Instead, these machines follow an *integration branch*,
+run tests on a nightly basis (or continuously during the day), and
+post to the `CMake CDash Page`_.  Some follow ``master``.  Most follow
+a special integration branch, the *topic stage*.
 
 The topic stage is a special branch maintained by the "Kitware Robot"
 (``@kwrobot``).  It consists of the head of the MR target integration
@@ -241,6 +241,8 @@ until one of the following occurs:
 Once a MR has been removed from the topic stage a new ``Do: stage``
 command is needed to stage it again.
 
+.. _`CMake Testing Process`: testing.rst
+
 Resolve
 =======
 

Help/dev/testing.rst

@@ -0,0 +1,42 @@
+CMake Testing Process
+*********************
+
+The following documents the process for running integration testing builds.
+See documentation on `CMake Development`_ for more information.
+
+.. _`CMake Development`: README.rst
+
+CMake Dashboard Scripts
+=======================
+
+The *integration testing* step of the `CMake Review Process`_ uses a set of
+testing machines that follow an integration branch on their own schedule to
+drive testing and submit results to the `CMake CDash Page`_.  Anyone is
+welcome to provide testing machines in order to help keep support for their
+platforms working.
+
+The `CMake Dashboard Scripts Repository`_ provides CTest scripts to drive
+nightly, continous, and experimental testing of CMake.  Use the following
+commands to set up a new integration testing client:
+
+.. code-block:: console
+
+  $ mkdir -p ~/Dashboards
+  $ cd ~/Dashboards
+  $ git clone https://gitlab.kitware.com/cmake/dashboard-scripts.git CMakeScripts
+  $ cd CMakeScripts
+
+The ``cmake_common.cmake`` script contains comments at the top with
+instructions to set up a testing client.  As it instructs, create a
+CTest script with local settings and include ``cmake_common.cmake``.
+
+.. _`CMake Review Process`: review.rst
+.. _`CMake CDash Page`: https://open.cdash.org/index.php?project=CMake
+.. _`CMake Dashboard Scripts Repository`: https://gitlab.kitware.com/cmake/dashboard-scripts
+
+Nightly Start Time
+------------------
+
+The ``cmake_common.cmake`` script expects its includer to be run from a
+nightly scheduled task (cron job).  Schedule such tasks for sometime after
+``1:00am UTC``, the time at which our nightly testing branches fast-forward.