From 7cc124d4b55aea0cd6f2439669f30c019d611d92 Mon Sep 17 00:00:00 2001 From: Brad King Date: Fri, 31 May 2024 14:33:22 -0400 Subject: Help/dev: Move integration testing to a more-specific document Avoid breaking existing links to `Help/dev/testing.rst` by keeping the document with minimal text to direct readers to the new one. --- CONTRIBUTING.rst | 4 ++-- Help/dev/README.rst | 5 +++-- Help/dev/integration-testing.rst | 43 ++++++++++++++++++++++++++++++++++++++++ Help/dev/review.rst | 4 ++-- Help/dev/testing.rst | 43 ++++------------------------------------ 5 files changed, 54 insertions(+), 45 deletions(-) create mode 100644 Help/dev/integration-testing.rst diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 81f26f5..302c38a 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -61,10 +61,10 @@ 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. -See documentation on `CMake Testing Process`_ for more information. +See documentation on `CMake Integration Testing`_ for more information. .. _`CMake CDash Page`: https://open.cdash.org/index.php?project=CMake -.. _`CMake Testing Process`: Help/dev/testing.rst +.. _`CMake Integration Testing`: Help/dev/integration-testing.rst License ======= diff --git a/Help/dev/README.rst b/Help/dev/README.rst index 9c3878b..abb4ac9 100644 --- a/Help/dev/README.rst +++ b/Help/dev/README.rst @@ -23,12 +23,13 @@ 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. +* The `CMake Integration Testing`_ infrastructure tests changes + before and after merging. .. _`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 +.. _`CMake Integration Testing`: integration-testing.rst Developer Documentation ======================= diff --git a/Help/dev/integration-testing.rst b/Help/dev/integration-testing.rst new file mode 100644 index 0000000..1b666d6 --- /dev/null +++ b/Help/dev/integration-testing.rst @@ -0,0 +1,43 @@ +CMake Integration Testing +************************* + +The following documents how to run 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, continuous, 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 +.. _`cmake_common.cmake`: https://gitlab.kitware.com/cmake/dashboard-scripts/-/blob/master/cmake_common.cmake + +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. diff --git a/Help/dev/review.rst b/Help/dev/review.rst index 34796a1..40bf3e5 100644 --- a/Help/dev/review.rst +++ b/Help/dev/review.rst @@ -348,7 +348,7 @@ Integration Testing The above `topic testing`_ tests the MR topic independent of other merge requests and on only a few key platforms and configurations. -The `CMake Testing Process`_ also has a large number of machines +`CMake Integration Testing`_ also uses 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 @@ -403,7 +403,7 @@ 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 +.. _`CMake Integration Testing`: integration-testing.rst Resolve ======= diff --git a/Help/dev/testing.rst b/Help/dev/testing.rst index 279e4b2..2179f60 100644 --- a/Help/dev/testing.rst +++ b/Help/dev/testing.rst @@ -1,43 +1,8 @@ -CMake Testing Process -********************* +CMake Testing Guide +******************* -The following documents the process for running integration testing builds. +See `CMake Integration Testing`_ for running integration testing builds. See documentation on `CMake Development`_ for more information. +.. _`CMake Integration Testing`: integration-testing.rst .. _`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, continuous, 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 -.. _`cmake_common.cmake`: https://gitlab.kitware.com/cmake/dashboard-scripts/-/blob/master/cmake_common.cmake - -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. -- cgit v0.12