Add instructions to run coverage

source/Contributing/ROS-2-On-boarding-Guide.rst

@@ -118,6 +118,16 @@ The usual workflow is (this list is a work in progress):
   * In the first box "CI_BRANCH_TO_TEST" enter your feature branch name
   * Hit the ``build`` button
 
+* If your use case requires running code coverage:
+
+  * Go to ci.ros2.org
+  * Log in (top right corner)
+  * Click on the ``ci_linux_coverage`` job
+  * Click "Build with Parameters" (left column)
+  * Be sure of leaving "CI_BUILD_ARGS" and "CI_TEST_ARGS" with the default values
+  * Hit the ``build`` button
+  * At the end of the document there are instructions on how to :ref:`interpret the result of the report <read-coverage-report>` and :ref:`calculate the coverage rate <calculate-coverage-rate>`
+
 * If built without warnings, errors and test failures, post the links of your jobs on your PR or high level ticket aggregating all your PRs (see example `here <https://github.com/ros2/rcl/pull/106#issuecomment-271119200>`__)
 
   * Note that the markdown for these badges is in the console output of the ``ci_launcher`` job
@@ -184,6 +194,7 @@ There several categories of jobs on the buildfarm:
 
   * ci_linux: build + test the code on Ubuntu Xenial
   * ci_linux-aarch64: build + test the code on Ubuntu Xenial on an ARM 64-bit machine (aarch64)
+  * ci_linux_coverage: build + test + generation of test coverage
   * ci_osx: build + test the code on MacOS 10.12
   * ci_windows: build + test the code on Windows 10
   * ci_launcher: trigger all the jobs listed above
@@ -217,12 +228,68 @@ There several categories of jobs on the buildfarm:
 
       * results are exported as a cobertura report
 
+
 * packaging (run every night, against fastrtps; result is bundled into an archive):
 
   * packaging_linux
   * packaging_osx
   * Packaging_windows
 
+Note on Coverage runs
+^^^^^^^^^^^^^^^^^^^^^
+
+ROS2 packages are organized in a way that the testing code for a given package is not only contained within the package, but could also be present in a different package.
+In other words: packages can exercise code belonging to other packages during the testing phase.
+
+To achieve the coverage rate reached by all code available in the ROS 2 core packages it is recommended to run builds using a fixed set of proposed repositories.
+That set is defined in the default parameters of coverage jobs in Jenkins.
+
+
+.. _read-coverage-report:
+
+How to read the coverage rate from the buildfarm report
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To see the coverage report for a given package:
+
+* When the ``ci_linux_coverage`` build finishes, click in ``Coverage Report``
+* Scroll down to the ``Coverage Breakdown by Package`` table
+* In the table, look at the first column called "Name"
+
+The coverage reports in the buildfarm include all the packages that were used in the ROS workspace.
+The coverage report includes different paths corresponding to the same package:
+
+* Name entries with the form: ``src.*.<repository_name>.<package_name>.*``
+  These correspond to the unit test runs available in a package against its own source code
+* Name entries with the form: ``build.<repository_name>.<package_name>.*``
+  These correspond to the unit test runs available in a package against its files generated at building or configuring time
+* Name entries with the form: ``install.<package_name>.*``
+  These correspond to the system/integration tests coming from testing runs of other packages
+
+.. _calculate-coverage-rate:
+
+How to calculate the coverage rate from the buildfarm report
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Get the combined unit coverage rate using the automatic script:
+
+ * From the ci_linux_coverage Jenkins build copy the URL of the build
+ * Download the `get_coverage_ros2_pkg <https://github.com/j-rivero/ros2_coverage_jenkins_params/blob/coverage_checker/get_coverage_results/get_coverage_ros2_pkg.py>`__ script
+ * Execute the script: ``./get_coverage_ros2_pkg.py <jenkins_build_url> <ros2_package_name>`` (`README <https://github.com/j-rivero/ros2_coverage_jenkins_params/blob/coverage_checker/get_coverage_results/README.md>`__)
+ * Grab the results from the "Combined unit testing" final line in the output of the script
+
+Alternative: get the combined unit coverage rate from coverage report (require manual calculation):
+
+* When the ci_linux_coverage build finishes, click on ``Cobertura Coverage Report``
+* Scroll down to the ``Coverage Breakdown by Package`` table
+* In the table, under the first column "Name", look for (where <package_name> is your package under testing):
+
+  * all the directories under the pattern ``src.*.<repository_name>.<package_name>.*`` grab the two absolute values in the column "Lines".
+  * all the directories under the pattern ``build/.<repository_name>.*`` grab the two absolute values in the column "Lines".
+
+* With the previous selection: for each cell, the first value is the lines tested and the second is the total lines of code.
+  Aggregate all rows for getting the total of the lines tested and the total of lines of code under test. Divide to get the coverage rate.
+
 Learning ROS 2 concepts at a high level
 ---------------------------------------