Add explanation to buildbots.rst about triggering buildbot on a PR (#1605)

Co-authored-by: Stan Ulbrych <[email protected]>
Co-authored-by: Hugo van Kemenade <[email protected]>

Author: 3 people

testing/buildbots.rst

@@ -48,6 +48,41 @@ after each commit. In particular, reference leaks builds take several hours to
 complete so they are done periodically. This is why it's important for you to
 be able to check the results yourself, too.
 
+Triggering buildbots on a pull request
+======================================
+
+To trigger buildbots on a pull request you need to be a CPython triager or a
+core team member. If you are not, ask someone to trigger them on your behalf.
+
+The simplest way to trigger most buildbots on your PR is with the
+:gh-label:`🔨 test-with-buildbots` and :gh-label:`🔨 test-with-refleak-buildbots`
+labels. (See :ref:`github-pr-labels`.)
+
+These will run buildbots on the most recent commit. If you want to trigger the
+buildbots again on a later commit, you'll have to remove the label and add it
+again.
+
+If you want to test a pull request against specific platforms, you can trigger
+one or more build bots by posting a comment that begins with:
+
+.. code-block:: none
+
+   !buildbot regex-matching-target
+
+For example to run both the iOS and Android build bot, you can use:
+
+.. code-block:: none
+
+   !buildbot ios|android
+
+bedevere-bot will post a comment indicating which build bots, if
+any, were matched. If none were matched, or you do not have the
+necessary permissions to trigger a request, it will tell you that too.
+
+The ``!buildbot`` comment will also only run buildbots on the most recent
+commit. To trigger the buildbots again on a later commit, you will have to
+repeat the comment.
+
 Checking results of automatic builds
 ====================================
 

triage/labels.rst

@@ -158,9 +158,13 @@ to trigger specific bot behaviors.
 * :gh-label:`skip news <skip%20news>`: for PRs that don't need a NEWS entry.
   The :ref:`news-entry` section covers in details in which cases the NEWS entry
   can be skipped.
-* :gh-label:`🔨 test-with-buildbots <%3Ahammer%3A%20test-with-buildbots>`: used to test the latest commit with
-  the :ref:`buildbot fleet <buildbots>` whenever more testing is required
-  before merging.  This may take multiple hours to complete.
+* :gh-label:`🔨 test-with-buildbots <%3Ahammer%3A%20test-with-buildbots>`: used
+  to test the latest commit with the :ref:`buildbot fleet <buildbots>` whenever
+  more testing is required before merging.  This may take multiple hours to
+  complete.
+* :gh-label:`🔨 test-with-refleak-buildbots <%3Ahammer%3A%20test-with-refleak-buildbots>`:
+  Run the reference leak buildbots on the latest commit. Useful for when the
+  code might be leaky.
 * :samp:`awaiting {action}`: these labels are applied and used by `bedevere`_
   to indicate the stage of a PR and should not be applied manually.