5 files changed, 101 insertions, 37 deletions
diff --git a/Help/cpack_gen/external.rst b/Help/cpack_gen/external.rst
index 406f6be..7ef1071 100644
--- a/Help/cpack_gen/external.rst
+++ b/Help/cpack_gen/external.rst
@@ -281,3 +281,10 @@ Variables specific to CPack External generator
   It is invoked after (optional) staging took place and may
   run an external packaging tool. The script has access to
   the variables defined by the CPack config file.
+
+.. variable:: CPACK_EXTERNAL_BUILT_PACKAGES
+
+  The ``CPACK_EXTERNAL_PACKAGE_SCRIPT`` script may set this list variable to the
+  full paths of generated package files.  CPack copy these files from the stage
+  directory back to the top build directory and possibly produce checksum files
+  if the :variable:`CPACK_PACKAGE_CHECKSUM` is set.
diff --git a/Help/dev/review.rst b/Help/dev/review.rst
index ad0bb22..6c7e92c 100644
--- a/Help/dev/review.rst
+++ b/Help/dev/review.rst
@@ -278,42 +278,52 @@ merging.
 Topic Testing
 =============
 
-CMake has a `buildbot`_ instance watching for merge requests to test.
-`CMake GitLab Project Developers`_ may activate buildbot on a MR by
-adding a comment with a command among the `comment trailing lines`_::
-
-  Do: test
-
-``@kwrobot`` will add an award emoji to the comment to indicate that it
-was processed and also inform buildbot about the request.  The buildbot
-user (``@buildbot``) will schedule builds and respond with a comment
-linking to the `CMake CDash Page`_ with a filter for results associated
-with the topic test request.  If the MR topic branch is updated by a
-push a new ``Do: test`` command is needed to activate testing again.
-
-The ``Do: test`` command accepts the following arguments:
-
-* ``--stop``: clear the list of commands for the merge request
-* ``--clear``: clear previous commands before adding this command
-* ``--regex-include <arg>`` or ``-i <arg>``: only build on builders
-  matching ``<arg>`` (a Python regular expression)
-* ``--regex-exclude <arg>`` or ``-e <arg>``: exclude builds on builders
-  matching ``<arg>`` (a Python regular expression)
-
-Builder names follow the pattern ``project-host-os-buildtype-generator``:
-
-* ``project``: always ``cmake`` for CMake builds
-* ``host``: the buildbot host
-* ``os``: one of ``windows``, ``osx``, or ``linux``
-* ``buildtype``: ``release`` or ``debug``
-* ``generator``: ``ninja``, ``makefiles``, ``vs<year>``,
-  or ``lint-iwyu-tidy``
-
-The special ``lint-<tools>`` generator name is a builder that builds
-CMake using lint tools but does not run the test suite (so the actual
-generator does not matter).
-
-.. _`buildbot`: http://buildbot.net
+CMake uses `GitLab CI`_ to test merge requests, configured by the top-level
+``.gitlab-ci.yml`` file.  Results may be seen both on the merge request's
+pipeline page and on the `CMake CDash Page`_.  Filtered CDash results
+showing just the pipeline's jobs can be reached by selecting the ``cdash``
+job in the ``External`` stage of the pipeline.
+
+Lint and documentation build jobs run automatically after every push.
+Heavier jobs require a manual trigger to run:
+
+* Merge request authors may visit their merge request's pipeline and click the
+  "Play" button on one or more jobs manually.  If the merge request has the
+  "Allow commits from members who can merge to the target branch" check box
+  enabled, CMake maintainers may use the "Play" button too.
+
+* `CMake GitLab Project Developers`_ may trigger CI on a merge request by
+  adding a comment with a command among the `comment trailing lines`_::
+
+    Do: test
+
+  ``@kwrobot`` will add an award emoji to the comment to indicate that it
+  was processed and also trigger all manual jobs in the merge request's
+  pipeline.
+
+  The ``Do: test`` command accepts the following arguments:
+
+  * ``--named <regex>``, ``-n <regex>``: Trigger jobs matching ``<regex>``
+    anywhere in their name.  Job names may be seen on the merge request's
+    pipeline page.
+  * ``--stage <stage>``, ``-s <stage>``: Only affect jobs in a given stage.
+    Stage names may be seen on the merge request's pipeline page.  Note that
+    the names are determined by what is in the ``.gitlab-ci.yml`` file and may
+    be capitalized in the web page, so lowercasing the webpage's display name
+    for stages may be required.
+  * ``--action <action>``, ``-a <action>``: The action to perform on the jobs.
+    Possible actions:
+
+    * ``manual`` (the default): Start jobs awaiting manual interaction.
+    * ``unsuccessful``: Start or restart jobs which have not completed
+      successfully.
+    * ``failed``: Restart jobs which have completed, but without success.
+    * ``completed``: Restart all completed jobs.
+
+If the merge request topic branch is updated by a push, a new manual trigger
+using one of the above methods is needed to start CI again.
+
+.. _`GitLab CI`: https://gitlab.kitware.com/help/ci/README.md
 .. _`CMake CDash Page`: https://open.cdash.org/index.php?project=CMake
 
 Integration Testing
diff --git a/Help/prop_test/DEPENDS.rst b/Help/prop_test/DEPENDS.rst
index 89c7553..5aa36b4 100644
--- a/Help/prop_test/DEPENDS.rst
+++ b/Help/prop_test/DEPENDS.rst
@@ -8,3 +8,15 @@ results of those tests are not considered, the dependency relationship is
 purely for order of execution (i.e. it is really just a *run after*
 relationship). Consider using test fixtures with setup tests if a dependency
 with successful completion is required (see :prop_test:`FIXTURES_REQUIRED`).
+
+Examples
+~~~~~~~~
+
+.. code-block:: cmake
+
+  add_test(NAME baseTest1 ...)
+  add_test(NAME baseTest2 ...)
+  add_test(NAME dependsTest12 ...)
+
+  set_tests_properties(dependsTest12 PROPERTIES DEPENDS "baseTest1;baseTest2")
+  # dependsTest12 runs after baseTest1 and baseTest2, even if they fail
diff --git a/Help/prop_test/REQUIRED_FILES.rst b/Help/prop_test/REQUIRED_FILES.rst
index fac357c..baf209c 100644
--- a/Help/prop_test/REQUIRED_FILES.rst
+++ b/Help/prop_test/REQUIRED_FILES.rst
@@ -1,7 +1,38 @@
 REQUIRED_FILES
 --------------
 
-List of files required to run the test.
+List of files required to run the test.  The filenames are relative to the
+test :prop_test:`WORKING_DIRECTORY` unless an absolute path is specified.
 
 If set to a list of files, the test will not be run unless all of the
 files exist.
+
+Examples
+~~~~~~~~
+
+Suppose that ``test.txt`` is created by test ``baseTest`` and ``none.txt``
+does not exist:
+
+.. code-block:: cmake
+
+  add_test(NAME baseTest ...)   # Assumed to create test.txt
+  add_test(NAME fileTest ...)
+
+  # The following ensures that if baseTest is successful, test.txt will
+  # have been created before fileTest is run
+  set_tests_properties(fileTest PROPERTIES
+    DEPENDS baseTest
+    REQUIRED_FILES test.txt
+  )
+
+  add_test(NAME notRunTest ...)
+
+  # The following makes notRunTest depend on two files. Nothing creates
+  # the none.txt file, so notRunTest will fail with status "Not Run".
+  set_tests_properties(notRunTest PROPERTIES
+    REQUIRED_FILES "test.txt;none.txt"
+  )
+
+The above example demonstrates how ``REQUIRED_FILES`` works, but it is not the
+most robust way to implement test ordering with failure detection.  For that,
+test fixtures are a better alternative (see :prop_test:`FIXTURES_REQUIRED`).
diff --git a/Help/release/dev/CPACK_EXTERNAL_BUILT_PACKAGES.rst b/Help/release/dev/CPACK_EXTERNAL_BUILT_PACKAGES.rst
new file mode 100644
index 0000000..af446d2
--- /dev/null
+++ b/Help/release/dev/CPACK_EXTERNAL_BUILT_PACKAGES.rst
@@ -0,0 +1,4 @@
+CPACK_EXTERNAL_BUILT_PACKAGES
+-----------------------------
+
+* :cpack_gen:`CPack External Generator` learned the :variable:`CPACK_EXTERNAL_BUILT_PACKAGES` variable.