Add tutorial covering how to enable PR testing on the ROS build farm. (ros2#4593)

* PR TESTING

* Update BuildFarmTesting.rst

* Switch note since only indexing is required not releasing.

Signed-off-by: Steven! Ragnarök <[email protected]>

---------

Signed-off-by: Steven! Ragnarök <[email protected]>
Co-authored-by: Steven! Ragnarök <[email protected]>

Author: DLu

source/Tutorials/Intermediate/Testing/BuildFarmTesting.rst

@@ -0,0 +1,64 @@
+.. BuildFarmTesting:
+
+Testing Your Code with the ROS Build Farm
+=========================================
+
+The `ROS 2 Build Farm <https://build.ros2.org/>`_ is incredibly powerful.
+In addition to creating binaries, it will also test pull requests by compiling and running all the tests for your ROS packages before the PR is merged.
+
+There are four prerequisites.
+
+ * The GitHub user `@ros-pull-request-builder <https://github.com/ros-pull-request-builder>`_ must have access to the repository.
+ * The GitHub repository must have the webhooks set up.
+ * `Your package must be indexed in rosdistro </How-To-Guides/Releasing/Index-Your-Packages>`
+ * The ``test_pull_requests`` flag must be true.
+
+
+GitHub Access
+-------------
+
+You can give access to the PR Builder either at the GitHub organization level OR just to the single GitHub repository.
+
+GitHub Organization
+^^^^^^^^^^^^^^^^^^^
+
+#. Open `https://github.com/orgs/%YOUR_ORG%/people <https://github.com/orgs/%YOUR_ORG%/people>`_
+   (while replacing ``%YOUR_ORG%`` with the appropriate organization)
+#. Click ``Invite Member`` and enter ``ros-pull-request-builder``
+
+
+GitHub Repository
+^^^^^^^^^^^^^^^^^
+
+#. Open `https://github.com/%YOUR_ORG%/%YOUR_REPO%/settings/access <https://github.com/%YOUR_ORG%/%YOUR_REPO%/settings/access>`_
+   (while replacing ``%YOUR_ORG%/%YOUR_REPO$`` with the appropriate organization/repo)
+#. Click ``Add people`` and enter ``ros-pull-request-builder``
+#. Select ``Admin`` or ``Write`` for their role. (see next section)
+
+
+WebHooks
+--------
+
+If you grant full administrative rights to ``ros-pull-request-builder``, it will automatically setup the hooks.
+
+Alternatively, you can avoid the need for full administrative rights by setting them up with only **write** permissions.
+
+#. Open `https://github.com/%YOUR_ORG%/%YOUR_REPO%/settings/hooks/new <https://github.com/%YOUR_ORG%/%YOUR_REPO%/settings/hooks/new>`_)
+#. Enter ``"https://build.ros2.org/ghprbhook/`` as the Payload URL
+#. Check the following options:
+    * Let me select individual events.
+    * Issue comments
+    * Pull requests
+
+
+test_pull_requests
+------------------
+
+For each ROS distro that you want pull request testing for, you must enable the ``test_pull_requests`` flag in the appropriate section of the `rosdistro <https://github.com/ros/rosdistro/>`_.
+
+ * **Option 1** - You have the option when running `bloom </How-To-Guides/Releasing/Releasing-a-Package>` to turn on pull request testing.
+ * **Option 2** - You can **carefully** manually edit the appropriate file in the rosdistro repo, and make a new pull request.
+   `Example <https://github.com/ros/rosdistro/blob/3c295f76b0755989e9ed526c0b5f28a5f6a94da3/rolling/distribution.yaml#L4708>`_.
+   `Documented in REP 143 <http://docs.ros.org/en/independent/api/rep/html/rep-0143.html#distribution-file>`_.
+
+Note that after the pull request has been added, the job will usually not be created until the nightly Jenkins reconfiguration.

source/Tutorials/Intermediate/Testing/Testing-Main.rst

@@ -41,3 +41,4 @@ Available Tutorials:
    CLI
    Cpp
    Python
+   BuildFarmTesting