[llvm][docs] Expand HowToAddABuilder with guidance on testing locally

llvm/docs/HowToAddABuilder.rst

@@ -179,6 +179,87 @@ Here are the steps you can follow to do so:
    buildbot.tac file to change the port number from 9994 to 9990 and start it
    again.
 
+Testing a Builder Config Locally
+================================
+
+It is possible to test a builder running against a local version of LLVM's
+buildmaster setup. This allows you to test changes to builder, worker, and
+buildmaster configuration. A buildmaster launched in this "local testing" mode
+will:
+* Bind only to local interfaces.
+* Use SQLite as the database.
+* Use a single fixed password for workers.
+* Disable extras like GitHub authentication.
+
+In order to use this "local testing" mode:
+
+* Within a checkout of `llvm-zorg <https://github.com/llvm/llvm-zorg>`_,
+  create and activate a Python `venv
+  <https://docs.python.org/3/library/venv.html>`_ and install the necessary
+  dependencies.
+
+    .. code-block:: bash
+
+       python -m venv bbenv
+       source bbenv/bin/activate
+       pip install buildbot{,-console-view,-grid-view,-waterfall-view,-worker,-www}==3.11.7 urllib3
+
+* Initialise the necessary buildmaster files, link to the configuration in
+  ``llvm-zorg`` and ask ``buildbot`` to check the configuration. This step can
+  be run from any directory.
+
+    .. code-block:: bash
+
+       buildbot create-master llvm-testbbmaster
+       cd llvm-testbbmaster
+       ln -s /path/to/checkout/of/llvm-zorg/buildbot/osuosl/master/master.cfg .
+       ln -s /path/to/checkout/of/llvm-zorg/buildbot/osuosl/master/config/ .
+       ln -s /path/to/checkout/of/llvm-zorg/zorg/ .
+       BUILDBOT_TEST=1 buildbot checkconfig
+
+* Start the buildmaster.
+
+    .. code-block:: bash
+
+       BUILDBOT_TEST=1 buildbot start --nodaemon .
+
+* After waiting a few seconds for startup to complete, you should be able to
+  open the web UI at ``http://localhost:8011``.  If there are any errors or
+  this isn't working, check ``twistd.log`` (within the current directory) for
+  more information.
+
+* You can now create and start a buildbot worker. Ensure you pick the correct
+  name for the worker associated with the build configuration you want to test
+  in ``buildbot/osuosl/master/config/builders.py``.
+
+    .. code-block:: bash
+
+       buildbot-worker create-worker <buildbot-worker-root-directory> \
+                       localhost:9990 \
+                       <buildbot-worker-name> \
+                       test
+       buildbot-worker start --nodaemon <buildbot-worker-root-directory>
+
+* Either wait until the poller sets off a build, or alternatively force a
+  build to start in the web UI.
+
+* Review the progress and results of the build in the web UI.
+
+This local testing configuration defaults to binding only to the loopback
+interface for security reasons.
+
+If you want to run the test worker on a different machine, or to run the
+buildmaster on a remote server, ssh port forwarding can be used to make
+connection possible. For instance, if running the buildmaster on a remote
+server the following command will suffice to make the web UI accessible via
+``http://localhost:8011`` and make it possible for a local worker to connect
+to the remote buildmaster by connecting to ``localhost:9900``:
+
+    .. code-block:: bash
+
+       ssh -N -L 8011:localhost:8011 -L 9990:localhost:9990 username@buildmaster_server_address
+
+
 Best Practices for Configuring a Fast Builder
 =============================================