OPENR-146: Create article for reporting an issue and update triaging

Author: keithkirkwood-3di

source/Contact.rst

@@ -33,52 +33,6 @@ If you see an issue on `Robotics Stack Exchange <https://robotics.stackexchange.
 Don't worry if you aren't sure if your response is correct.
 Simply say so, and other community members will jump in if necessary.
 
-Issues
-------
-
-If you identify bugs, have suggestions for improvements, or a question specific to one package, you can open an issue on GitHub.
-
-For example, if you are following the :doc:`tutorials here <Tutorials>` and come across an instruction that doesn't work on your system,
-you can open an issue in the `ros2_documentation <https://github.com/ros2/ros2_documentation>`__ repo.
-
-You can search for individual ROS 2 repositories on `ROS 2's GitHub <https://github.com/ros2>`__.
-
-Before opening an issue, check if other users have reported similar issues by searching across the ros2 and ament GitHub organizations: `example search query <https://github.com/search?q=user%3Aros2+user%3Aament+turtlesim&type=Issues>`__.
-
-Next, check `Robotics Stack Exchange <https://robotics.stackexchange.com/>`__ to see if someone else has asked your question or reported your issue.
-
-If it has not been reported, feel free to open an issue in the appropriate repository tracker.
-If it's not clear which tracker to use for a particular issue, file it in the `ros2/ros2 repository <https://github.com/ros2/ros2/issues>`__ and we'll have a look at it.
-
-When filing an issue, please make sure to:
-
-* Include enough information for another person to understand the issue.
-
-Describe exactly what you were doing or are trying to do, and exactly what, if anything, went wrong.
-If following a tutorial or online instructions provide a link to the specific instructions.
-
-* Use a descriptive headline or subject line.
-  Bad: "rviz doesn't work".
-  Good: "Rviz crashing looking for missing ``.so`` after latest apt update"
-* Include information about the exact platform, software, versions, and environment relevant to the problem.
-  This includes how you installed the software (from binaries or from source) and which ROS middleware/DDS vendor you are using (if you know it).
-* Any warnings or errors.
-  Cut and paste them directly from the terminal window to which they were printed.
-  Please do not re-type or include a screenshot.
-* In case of a bug consider providing a `short, self contained, correct (compilable), example <https://sscce.org/>`__.
-* When discussing any compiling/linking/installation issues, also provide the compiler version
-
-As appropriate, also include your:
-
-* ROS environment variables (env | grep ROS)
-* Backtraces
-* Relevant config files
-* Graphics card model and driver version
-* Ogre.log for rviz, if possible (run with rviz -l)
-* Bag files and code samples that can reproduce the problem
-* Gifs or movies to demonstrate the problem
-
-
 Pull requests
 -------------
 

source/The-ROS2-Project/Contributing/Contributing-to-code/Reporting-an-issue.rst

@@ -1,4 +1,128 @@
 Reporting an issue — how-to
 ===========================
 
+Issue reports help the ROS community identify bugs, suggest enhancements, improve documentation, and resolve package-specific problems.
+This article explains how to check whether an issue has already been reported and what information to provide in a new issue.
+With this information, you can provide clear, complete issue details in the right ROS repository.
+
+**Area: community | Content-type: how-to | Experience: beginner, intermediate, expert**
+
+.. contents:: Table of Contents
+   :depth: 2
+   :local:
+
+Summary
+-------
+
+* **Documentation issue tracker**: `ROS documentation repository <https://github.com/ros2/ros2_documentation/issues>`__.
+* **Code issues lists**: in a repository under the `ROS organisation <https://github.com/orgs/ros2/repositories>`__.
+* **Catch-all issues list**: `top level ROS repository <https://github.com/ros2/ros2/issues>`__.
+
+Prerequisites
+-------------
+
+There are no prerequisites.
+
+Steps
+-----
+
+1 Checking the issue
+^^^^^^^^^^^^^^^^^^^^
+
+If you identify bugs, have suggestions for enhancements, or a question specific to one package, you can open an issue on GitHub.
+For example, if you are following the :doc:`/Tutorials` and come across an instruction that doesn't work on your system, you can open an issue in the `ROS documentation <https://github.com/ros2/ros2_documentation>`__ repo.
+
+You can search for individual ROS repositories on `ROS GitHub <https://github.com/ros2>`__.
+
+Before opening an issue:
+
+#. Check if other users have reported similar issues by searching across the ``ros2`` and ``ament`` GitHub organizations using, for example, this search query: `<https://github.com/search?q=user%3Aros2+user%3Aament+turtlesim&type=Issues>`__.
+#. Check the `Robotics Stack Exchange <https://robotics.stackexchange.com/>`__ to see if someone else has already reported your issue.
+
+If your issue has not been reported, you can open an issue in the appropriate repository's issue tracker.
+If it's not clear which tracker to use for a particular issue, create it in the `ros2/ros2 repository <https://github.com/ros2/ros2/issues>`__ and we'll have a look at it.
+
+2 Reporting the issue
+^^^^^^^^^^^^^^^^^^^^^
+
+When reporting an issue, use the following guidelines to make sure you include enough information for another person to understand and (where relevant) reproduce the issue.
+It's particularly helpful if you test for your issue with as many alternatives as you can in each category.
+
+Required information
+""""""""""""""""""""
+
+#. Use a descriptive **title** for the issue.
+
+   **Bad**: "rviz doesn't work".
+
+   **Good**: "Rviz crashing looking for missing ``.so`` after latest apt update"
+
+#. Add steps to the issue **description** describing exactly how to reproduce the issue.
+   If you are following a ROS tutorial or online instructions, provide a link to those specific instructions.
+
+   Issues are more likely to be resolved if others can reproduce them easily.
+
+#. Include the following information:
+
+   * **Operating system and version**
+
+     ROS supports multiple platforms, and some bugs are specific to particular versions of operating systems/compilers.
+
+   * **Installation method**
+
+     Some issues only manifest if ROS has been installed from binary archives or from deb packages.
+     This can help us determine if the issue is with the packaging process.
+
+   * **Specific version of ROS**
+
+     Some bugs may be present in a particular ROS release, but fixed in a later release.
+     It is important to know if your installation includes these fixes.
+
+   * **DDS/RMW implementation** (see `this page </Concepts/Intermediate/About-Different-Middleware-Vendors>` for how to determine which one).
+
+     Communication issues may be specific to the underlying ROS middleware being used.
+
+   * **ROS client library**
+
+     This helps us narrow down the layer in the stack where the issue might be.
+
+#. Include any warnings or errors which are displayed as part of the issue.
+
+   Cut and paste the warnings or errors directly from the terminal window to which they were printed.
+   Please do not re-type the warnings or errors or use screenshots of the terminal.
+
+Useful additional information
+"""""""""""""""""""""""""""""
+
+* If you are reporting a bug, consider providing a `short, self contained, correct (compilable) example <https://sscce.org/>`__.
+* When discussing any compiling/linking/installation issues, provide the version number of your compiler.
+* If relevant to your issue, you can also include your:
+
+  * ROS environment variables (``env | grep ROS``)
+  * Backtraces
+  * Relevant config files
+  * Graphics card model and driver version
+  * ``Ogre.log`` for rviz, if possible (run with ``rviz -l``)
+  * Bag files and code samples which reproduce the problem
+  * GIFs or video clips to demonstrate the problem
+
+* Also describe any troubleshooting which you have already attempted, for example:
+
+  * Upgrading to the latest version of the code, which may include bug fixes that have not been released yet.
+
+    For more information, see :ref:`building-from-source` and follow the instructions to get the ``rolling`` branch.
+
+  * Trying to reproduce your issue with a different RMW implementation.
+
+    For more information, see :doc:`../../../How-To-Guides/Working-with-multiple-RMW-implementations`.
+
+Related content
+---------------
+
+* :doc:`../../Contributing`
+* :doc:`Triaging-an-issue`
+
+FAQs
+----
+
 TBC

source/The-ROS2-Project/Contributing/Contributing-to-code/Triaging-an-issue.rst

@@ -14,9 +14,14 @@ With this information, you'll be able to route issues to the right place, with c
 Summary
 -------
 
-* **Documentation issues list**: `ROS documentation repository <https://github.com/ros2/ros2_documentation/issues>`__.
-* **Code issues lists**: in a repository under the `ROS organisation <https://github.com/orgs/ros2/repositories>`__.
-* **Catch-all issues list**: `top level ROS repository <https://github.com/ros2/ros2>`__.
+* **Code issue trackers**: in a repository under the `ROS organization <https://github.com/orgs/ros2/repositories>`__.
+* **Documentation issue tracker**: `ROS documentation repository <https://github.com/ros2/ros2_documentation/issues>`__.
+* **Catch-all issue tracker**: `top level ROS repository <https://github.com/ros2/ros2>`__.
+
+Prerequisites
+-------------
+
+There are no prerequisites.
 
 Steps
 -----
@@ -26,25 +31,27 @@ Steps
 
 We encourage contributors to look at incoming issues on ROS repositories and triage the problems that users are having:
 
-* To find documentation issues for triage, review the issues list in the `ROS documentation repository <https://github.com/ros2/ros2_documentation/issues>`__.
-* To find code issues for triage, review the issues list of a repository under the `ROS organisation <https://github.com/orgs/ros2/repositories>`__, for example the issues list in the `ROS CLI repo <https://github.com/ros2/ros2cli/issues/>`__.
-* If you're not sure where to start, review the issues list in the `top level ROS repository <https://github.com/ros2/ros2>`__ for triage.
+* To find code issues for triage, review the issues list of a repository under the `ROS organization <https://github.com/orgs/ros2/repositories>`__, for example the issues list in the `ROS CLI repository <https://github.com/ros2/ros2cli/issues/>`__.
+* To find documentation issues for triage, review the issues list in the `ROS documentation repository <https://github.com/ros2/ros2_documentation>`__.
+* If you're not sure where to start, review the issues list in the `top level ROS repository <https://github.com/ros2/ros2>`__.
+
+When you have identified an issue for triage, add a comment to the issue to say that you are looking into it.
 
 2 Confirming and reproducing the issue
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 When you have found an issue to triage, confirm that the issue is genuinely an issue (a bug or a request for enhancement) and has been created with the expected information.
 
-For more information about the information which the reporter of the issue is expected to provide, see :doc:`./Reporting-an-issue`.
+For more information about the information the reporter of the issue is expected to provide, see :doc:`./Reporting-an-issue`.
 
 #. If the issue ``Description`` is actually posing a question, close the issue and add a comment directing the user to the `Robotics Stack Exchange <https://robotics.stackexchange.com/>`__ to get help with their question.
-#. If the issue looks like a genuine issue (bug or enhancement), but is not relevant to the repo it has been raised in, transfer the issue to the appropriate ROS repository (`see the GitHub documentation for guidance <https://docs.github.com/en/issues/tracking-your-work-with-issues/administering-issues/transferring-an-issue-to-another-repository>`__).
+#. If the issue looks like a genuine issue (bug or enhancement), but is not relevant to the repository it has been raised in, transfer the issue to the appropriate ROS repository (`see the GitHub documentation for guidance about how to transfer between repositories <https://docs.github.com/en/issues/tracking-your-work-with-issues/administering-issues/transferring-an-issue-to-another-repository>`__).
 #. If the issue is a bug, try to reproduce the bug using the provided steps — if you cannot reproduce the bug, add a comment to the reporter asking for clarification.
 
 3 Assigning and labelling the issue
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-After you've confirmed the issue is a genuine issue, and reproduced it (if the issue is a bug), assign and label the issue appropriately to allow work on the issue to begin by a developer.
+After you've confirmed the issue is a genuine issue, and reproduced it, assign and label the issue appropriately to allow work on the issue to begin by a developer.
 
 #. Assign the issue to the appropriate developer for the ROS repository in question.
 #. Label the issue as a ``bug`` or ``enhancement``, as appropriate.
@@ -54,7 +61,8 @@ After you've confirmed the issue is a genuine issue, and reproduced it (if the i
 Related content
 ---------------
 
-* :doc:`/The-ROS2-Project/Contributing`
+* :doc:`../../Contributing`
+* :doc:`Reporting-an-issue`
 
 FAQs
 ----

source/The-ROS2-Project/Contributing/Developer-Guide.rst

@@ -271,39 +271,6 @@ Some practices are common to all ROS 2 development.
 
 These practices don't affect package quality level as described in `REP 2004 <https://reps.openrobotics.org/rep-2004/>`_, but are still highly recommended for the development process.
 
-Issues
-^^^^^^
-
-When filing an issue please make sure to:
-
-- Include enough information for another person to understand the issue.
-  In ROS 2, the following points are needed for narrowing down the cause of an issue.
-  Testing with as many alternatives in each category as feasible will be especially helpful.
-
-  - **The operating system and version.**
-    Reasoning: ROS 2 supports multiple platforms, and some bugs are specific to particular versions of operating systems/compilers.
-  - **The installation method.**
-    Reasoning: Some issues only manifest if ROS 2 has been installed from binary archives or from debs.
-    This can help us determine if the issue is with the packaging process.
-  - **The specific version of ROS 2.**
-    Reasoning: Some bugs may be present in a particular ROS 2 release and later fixed.
-    It is important to know if your installation includes these fixes.
-  - **The DDS/RMW implementation being used** (see `this page <../../Concepts/Intermediate/About-Different-Middleware-Vendors>` for how to determine which one).
-    Reasoning: Communication issues may be specific to the underlying ROS middleware being used.
-  - **The ROS 2 client library being used.**
-    Reasoning: This helps us narrow down the layer in the stack at which the issue might be.
-
-- Include a list of steps to reproduce the issue.
-- In case of a bug consider to provide a `short, self contained, correct (compilable), example <http://sscce.org/>`__.
-  Issues are much more likely to be resolved if others can reproduce them easily.
-
-- Mention troubleshooting steps that have been tried already, including:
-
-  - Upgrading to the latest version of the code, which may include bug fixes that have not been released yet.
-    See `this section <building-from-source>` and follow the instructions to get the "rolling" branches.
-  - Trying with a different RMW implementation.
-    See `this page <../../How-To-Guides/Working-with-multiple-RMW-implementations>` for how to do that.
-
 Branches
 ^^^^^^^^