[llvm] 73f4f56 - [llvm][docs] Update "Adding a Builder" docs

[David Spickett via llvm-commits]

Author: David Spickett
Date: 2023-04-24T10:58:35+01:00
New Revision: 73f4f56c9fc87f81e3172dcf101ca63c772032a6

URL: https://github.com/llvm/llvm-project/commit/73f4f56c9fc87f81e3172dcf101ca63c772032a6
DIFF: https://github.com/llvm/llvm-project/commit/73f4f56c9fc87f81e3172dcf101ca63c772032a6.diff

LOG: [llvm][docs] Update "Adding a Builder" docs

* Move step 8 to later, after worker credentials have
  been added to the buildmaster.
* Added command for starting the worker, in addition
  to creating the worker. The latter only sets up the
  directories.
* Noted that in step 6, it is expected that you get a
  refused connection.
* Stated that the connection should be tried once,
  and the worker then stopped.

We could mention that repeated connections with invalid
credentials will result in an IP ban, but it's probably
detail people don't need here.

If it did happen, then you would not know until you tried
the later steps. At which point you are already in contact
with Galina, who is the person who would help you with that
issue in any case.

Reviewed By: gkistanova

Differential Revision: https://reviews.llvm.org/D148913

Added: 
    

Modified: 
    llvm/docs/HowToAddABuilder.rst

Removed: 
    


################################################################################
diff  --git a/llvm/docs/HowToAddABuilder.rst b/llvm/docs/HowToAddABuilder.rst
index 76763cd1f8c75..e0ac34769fd07 100644
--- a/llvm/docs/HowToAddABuilder.rst
+++ b/llvm/docs/HowToAddABuilder.rst
@@ -63,8 +63,8 @@ Here are the steps you can follow to do so:
    will get feedback sooner after changes get committed.
 
 #. The computer you will be registering with the LLVM buildbot
-   infrastructure should have all dependencies installed and you can
-   actually build your configuration successfully. Please check what degree
+   infrastructure should have all dependencies installed and be able to
+   build your configuration successfully. Please check what degree
    of parallelism (-j param) would give the fastest build.  You can build
    multiple configurations on one computer.
 
@@ -92,11 +92,25 @@ Here are the steps you can follow to do so:
                     <buildbot-worker-access-name> \
                     <buildbot-worker-access-password>
 
-   This will cause your new worker to connect to the staging buildmaster
-   which is silent by default.  Only once a new worker is stable, and
+   Only once a new worker is stable, and
    approval from Galina has been received (see last step) should it
    be pointed at the main buildmaster.
 
+   Now start the worker:
+
+    .. code-block:: bash
+
+       $ buildbot-worker start <buildbot-worker-root-directory>
+
+   This will cause your new worker to connect to the staging buildmaster
+   which is silent by default.
+
+   Try this once then check the log file
+   ``<buildbot-worker-root-directory>/worker/twistd.log``. If your settings
+   are correct you will see a refused connection. This is good and expected,
+   as the credentials have not been established on both ends. Now stop the
+   worker and proceed to the next steps.
+
 #. Fill the buildbot-worker description and admin name/e-mail.  Here is an
    example of the buildbot-worker description::
 
@@ -108,10 +122,8 @@ Here are the steps you can follow to do so:
        cmake version 2.8.4
        Microsoft(R) 32-bit C/C++ Optimizing Compiler Version 16.00.40219.01 for 80x86
 
-#. Make sure you can actually start the buildbot-worker successfully. Then set
-   up your buildbot-worker to start automatically at the start up time.  See the
-   buildbot documentation for help.  You may want to restart your computer
-   to see if it works.
+   See `here <http://docs.buildbot.net/current/manual/installation/worker.html>`_
+   for which files to edit.
 
 #. Send a patch which adds your build worker and your builder to
    `zorg <https://github.com/llvm/llvm-zorg>`_. Use the typical LLVM
@@ -138,10 +150,15 @@ Here are the steps you can follow to do so:
    otherwise.
 
 #. Send the buildbot-worker access name and the access password directly to
-   `Galina Kistanova <mailto:gkistanova at gmail.com>`_, and wait till she
-   will let you know that your changes are applied and buildmaster is
+   `Galina Kistanova <mailto:gkistanova at gmail.com>`_, and wait until she
+   lets you know that your changes are applied and buildmaster is
    reconfigured.
 
+#. Make sure you can start the buildbot-worker and successfully connect
+   to the silent buildmaster. Then set up your buildbot-worker to start
+   automatically at the start up time.  See the buildbot documentation
+   for help.  You may want to restart your computer to see if it works.
+
 #. Check the status of your buildbot-worker on the `Waterfall Display (Staging)
    <http://lab.llvm.org/staging/#/waterfall>`_ to make sure it is
    connected, and the `Workers Display (Staging)