Move documentation from TestingLibcxx.rst to Contributing.rst

Also update & correct some of the documentation.

Author: cmtice

libcxx/docs/Contributing.rst

@@ -175,7 +175,7 @@ Introduction
 ------------
 
 Unlike most parts of the LLVM project, libc++ uses a pre-commit CI [#]_. This
-CI is hosted on `Buildkite <https://buildkite.com/llvm-project/libcxx-ci>`__ and
+CI used to be hosted on `Buildkite <https://buildkite.com/llvm-project/libcxx-ci>`__, but has migrated to the LLVM CI infrastrcuture, and
 the build results are visible in the review on GitHub. Please make sure
 the CI is green before committing a patch.
 
@@ -246,12 +246,15 @@ Below is a short description of the most interesting CI builds [#]_:
 Infrastructure
 --------------
 
-All files of the CI infrastructure are in the directory ``libcxx/utils/ci``.
-Note that quite a bit of this infrastructure is heavily Linux focused. This is
-the platform used by most of libc++'s Buildkite runners and developers.
+The files for the CI infrastructure are split between the llvm-project
+and the llvm-zorg repositories.  All files of the CI infrastructure in
+the llvm-project are in the directory ``libcxx/utils/ci``.  Note that
+quite a bit of this infrastructure is heavily Linux focused. This is
+the platform used by most of libc++'s Buildkite runners and
+developers.
 
-Dockerfile
-~~~~~~~~~~
+Dockerfile/Container Images
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Contains the Docker image for the Ubuntu CI. Because the same Docker image is
 used for the ``main`` and ``release`` branch, it should contain no hard-coded
@@ -261,6 +264,67 @@ GCC, and CMake.
 .. note:: This image is pulled from Docker hub and not rebuild when changing
    the Dockerfile.
 
+Updating the CI testing container images
+----------------------------------------
+
+The libcxx linux premerge testing can run on one of three sets of
+runner groups. The three runner group names are
+"llvm-premerge-libcxx-runners", "llvm-premerge-libcxx-release-runners"
+or "llvm-premerge-libcxx-next-runners".  Which runner set to use is
+controlled by the contents of https://github.com/llvm/llvm-project/blob/main/.github/workflows/libcxx-build-and-test.yaml . By default, it uses
+"llvm-premerge-libcxx-runners". To switch to one of the other runner
+sets, just replace all uses of "llvm-premerge-libcxx-runners" in the yaml
+file with the desired runner set.
+
+Which container image is used by these three runner sets is controlled
+and set by the variable values in
+https://github.com/llvm/llvm-zorg/blob/main/premerge/premerge_resources/variables.tf.
+The table below shows the variable names and
+the runner sets to which they correspond. To see their values, follow the
+link above (to variables.tf in llvm-zorg).
+
++------------------------------------+---------------------------+
+|Runner Set                          |Variable                   |
++====================================+===========================+
+|llvm-premerge-libcxx-runners        |libcxx_runner_image        |
++------------------------------------+---------------------------+
+|llvm-premerge-libcxx-release-runners|libcxx_release_runner_image|
++------------------------------------+---------------------------+
+|llvm-premerge-libcxx-next-runners   |libcxx_next_runner_image   |
++------------------------------------+---------------------------+
+
+
+When updating the container image you can either update just the
+runner binary (the part the connects to Github), or you can update
+everything (tools, etc.). Whether to update just the runner or to update
+everything is controlled by the value of ``ACTIONS_BASE_IMAGE``, under
+``actions-builder`` in ``libcxx/utils/ci/docker-compose.yml``.
+
+To update just the runner binary, change the value of
+``ACTIONS_BASE_IMAGE`` to be one of the libcxx runner variable images
+from
+https://github.com/llvm/llvm-zorg/blob/main/premerge/premerge_resources/variables.tf.
+
+To update the entire container image, set the value of ``ACTIONS_BASE_IMAGE``
+to ``builder-base``. If the value is already ``builder-base`` (there
+have been no just-the-runner updates since the last complete update), then
+you need to find the line containing
+``RUN echo "Last forced update executed on`` in
+``libcxx/utils/ci/Dockerfile`` and update the date to be the current date.
+
+Once you have created and merged a PR with those changes, a new image
+will be created, and a link to it can be found at
+https://github.com/llvm/llvm-project/pkgs/container/libcxx-linux-builder.,
+where the actual image name should be
+``ghcr.io/llvm/libcxx-linux-builder:<SHA-of-committed-change-from-PR>``.
+
+Lastly you need to create a PR in the llvm-zorg repository,
+updating the the value of the appropriate libcxx runner variable in
+the variables.tf file mentioned above. Once that change has been
+merged, an llvm-zorg administrator must use terraform to apply the
+change to the running GKE cluster.
+
+
 run-buildbot-container
 ~~~~~~~~~~~~~~~~~~~~~~
 

libcxx/docs/TestingLibcxx.rst

@@ -139,43 +139,6 @@ Also note that the Docker container shares the same filesystem as your local mac
 modifying files on your local machine will also modify what the Docker container sees.
 This is useful for editing source files as you're testing your code in the Docker container.
 
-Updating the CI testing container images
-----------------------------------------
-
-The libcxx linux premerge testing can run on one of three sets of
-runner groups. The three runner group names are
-"llvm-premerge-libcxx-runners", "llvm-premerge-libcxx-release-runners"
-or "llvm-premerge-libcxx-next-runners".  Which runner set to use is
-controlled by the contents of https://github.com/llvm/llvm-project/blob/main/.github/workflows/libcxx-build-and-test.yaml . By default, it uses
-"llvm-premerge-libcxx-runners". To switch to one of the other runner
-sets, just replace all uses of "llvm-premerge-libcxx-runners" in the yaml
-file with the desired runner set.
-
-Which container image is used by these three runner sets is controlled
-and set by the variable values in
-https://github.com/llvm/llvm-zorg/blob/main/premerge/premerge_resources/variables.tf.
-The table below shows the variable names, their current values, and
-the runner sets to which they correspond.
-
-+------------------------------------+---------------------------+--------------------------------------------------------------------------+
-|Runner Set                          |Variable                   |Image Value                                                               |
-+====================================+===========================+==========================================================================+
-|llvm-premerge-libcxx-runners        |libcxx_runner_image        |ghcr.io/llvm/libcxx-linux-builder:16f046281bf1a11d344eac1bc44d11f3e50e3b5d|
-+------------------------------------+---------------------------+--------------------------------------------------------------------------+
-|llvm-premerge-libcxx-release-runners|libcxx_release_runner_image|ghcr.io/llvm/libcxx-linux-builder:16f046281bf1a11d344eac1bc44d11f3e50e3b5d|
-+------------------------------------+---------------------------+--------------------------------------------------------------------------+
-|llvm-premerge-libcxx-next-runners   |libcxx_next_runner_image   |ghcr.io/llvm/libcxx-linux-builder:16f046281bf1a11d344eac1bc44d11f3e50e3b5d|
-+------------------------------------+---------------------------+--------------------------------------------------------------------------+
-
-Note: The three runner images are (temporarily) all the same, but that
-will not normally be the case.
-
-To change the container image, the variable.tf file in llvm-zorg must
-be changed. Once that change has been merged, an llvm-zorg
-administrator must use terraform to apply the change to the running
-GKE cluster.
-
-
 Writing Tests
 =============