From c892746338b524c266b3e0a6579e45449d654b9b Mon Sep 17 00:00:00 2001 From: Keith Kirkwood Date: Fri, 31 Jul 2026 08:31:41 +0100 Subject: [PATCH] 3di | Triaging and reporting an issue (#6901) * OPENR-98: Create article for triaging an issue * OPENR-146: Create article for reporting an issue and update triaging * OPENR-146: Fix link issue for linter and add sentence to summary * OPENR-146: Updates to Reporting an issue from PR comments * Update source/The-ROS2-Project/Contributing/Contributing-to-code/Triaging-an-issue.rst Signed-off-by: Katherine Scott * OPENR-98: Action comments for Triaging and tidy up * OPENR-98: Fix typo in Triaging * Correct broken references Signed-off-by: Geoffrey Biggs --------- Signed-off-by: Katherine Scott Signed-off-by: Geoffrey Biggs Co-authored-by: Katherine Scott Co-authored-by: Geoffrey Biggs Co-authored-by: Tully Foote (cherry picked from commit bf9db7418b572fea5fd393ee57e9f5b212041194) # Conflicts: # source/Contact.rst # source/The-ROS2-Project/Contributing/Developer-Guide.rst --- source/Contact.rst | 3 + .../How-To-Guides/Core-maintainer-guide.rst | 16 --- .../Contributing/Contributing-to-code.rst | 2 + .../Reporting-an-issue.rst | 111 ++++++++++++++++++ .../Triaging-an-issue.rst | 77 ++++++++++++ .../Contributing/Developer-Guide.rst | 3 + 6 files changed, 196 insertions(+), 16 deletions(-) create mode 100644 source/The-ROS2-Project/Contributing/Contributing-to-code/Reporting-an-issue.rst create mode 100644 source/The-ROS2-Project/Contributing/Contributing-to-code/Triaging-an-issue.rst diff --git a/source/Contact.rst b/source/Contact.rst index 1e3acca25fa..7e0e6799604 100644 --- a/source/Contact.rst +++ b/source/Contact.rst @@ -33,6 +33,7 @@ If you see an issue on `Robotics Stack Exchange >>>>>> bf9db74 (3di | Triaging and reporting an issue (#6901)) .. _Using ROS Discourse: Discussion diff --git a/source/How-To-Guides/Core-maintainer-guide.rst b/source/How-To-Guides/Core-maintainer-guide.rst index cd1f4646e43..d6f460e947f 100644 --- a/source/How-To-Guides/Core-maintainer-guide.rst +++ b/source/How-To-Guides/Core-maintainer-guide.rst @@ -141,22 +141,6 @@ If a change can be backported without breaking API or ABI, then a new pull reque The new pull request should be added to the appropriate distributions project board at https://github.com/orgs/ros2/projects. The new pull request should have all of the steps run as before, but making sure to target the distribution in question for CI, etc. -Responding to issues --------------------- - -Package maintainers should also look at incoming issues on the repository and triage the problems that users are having. - -For issues that look like questions, the issue should be closed and the user redirected to `Robotics Stack Exchange `__ . - -If an issue looks like a problem, but is not relevant to this particular repository, it should be moved to the appropriate repository with the GitHub "Transfer issue" button. - -If the reporter has not provided enough information to determine the cause of the problem, more information should be requested from the reporter. - -If this is a new feature, tag the issue with "help-wanted". - -Any remaining issues should be reproduced, and determined if they are truly a bug. -If it is a bug, fixes are highly appreciated. - Getting help ------------ diff --git a/source/The-ROS2-Project/Contributing/Contributing-to-code.rst b/source/The-ROS2-Project/Contributing/Contributing-to-code.rst index a380d548de1..4c59519dc1e 100644 --- a/source/The-ROS2-Project/Contributing/Contributing-to-code.rst +++ b/source/The-ROS2-Project/Contributing/Contributing-to-code.rst @@ -4,5 +4,7 @@ Contributing to code .. toctree:: :maxdepth: 1 + Contributing-to-code/Triaging-an-issue + Contributing-to-code/Reporting-an-issue Contributing-to-code/Making-a-PR Contributing-to-code/Reviewing-a-PR diff --git a/source/The-ROS2-Project/Contributing/Contributing-to-code/Reporting-an-issue.rst b/source/The-ROS2-Project/Contributing/Contributing-to-code/Reporting-an-issue.rst new file mode 100644 index 00000000000..1bb560f9df5 --- /dev/null +++ b/source/The-ROS2-Project/Contributing/Contributing-to-code/Reporting-an-issue.rst @@ -0,0 +1,111 @@ +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 +------- + +* **Code issue trackers**: in a repository under the `ROS organisation `__ or elsewhere on GitHub. +* **Documentation issue tracker**: `ROS documentation repository `__. +* **Catch-all issue tracker**: `top level ROS repository `__. + +Prerequisites +------------- + +There are no prerequisites. + +Steps +----- + +1 Identifying where to report the issue +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If you identify a bug, have a suggestion for enhancement, or a question specific to one package, you can report an issue on GitHub. +For example, if you are following a :doc:`tutorial ` and come across an instruction that doesn't work on your system, you can report an issue in the `ROS documentation repository `__. + +You can report code issues in the ROS repository for the package where the error occurred. +This is generally the last file listed in the stack trace. + +You can search for ROS packages in the following locations: + +* Core ROS 2 packages, found in the `ROS organisation `__ +* ROS binary packages, found on the `ROS Index `__, which point to the appropriate GitHub repository. +* Source ROS packages which are located elsewhere on GitHub. + +If it's not clear which issue tracker to use for a particular issue, report the issue in the `top-level ROS repository `__ and we'll have a look at it. + +2 Checking the issue +^^^^^^^^^^^^^^^^^^^^ + +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 `__. +#. Check the `Robotics Stack Exchange `__ to see if someone else has already reported your issue. + +If your issue has not been reported, you can open an issue in the issue tracker of the repository you have identified. + +3 Reporting the issue +^^^^^^^^^^^^^^^^^^^^^ + +When reporting an issue, use the following steps to make sure you include enough information for another person to understand and (where relevant) reproduce the issue. + +#. In the issue tracker of your selected repository, select **New issue**. +#. From the options shown, select the issue type which is most appropriate for the issue you are raising: + + * If you are in a ROS code repository or the top-level ROS repository, select **Bug report** or **Feature request**. + * If you are in the ROS documentation repository, select **Documentation issue**. + * Alternatively, if the specific ROS repository you are in has a unique issue template, you can use that instead. + +#. Add a descriptive **Title** for the issue. + + **Bad**: "rviz doesn't work". + + **Good**: "Rviz crashing looking for missing ``.so`` after latest apt update" + +#. Complete the remaining fields in the issue template, following the prompt text shown and the formatting of any pre-filled fields. + +Additional information +"""""""""""""""""""""" + +* If you are reporting a bug, consider providing a `short, self contained, correct (compilable) example `__. +* 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 + * Log files (see :doc:`/ROS-Framework/nodes/About-Logging/About-Logging`) or logs from the RQT console (see :doc:`/ROS-Framework/nodes/Working-with-nodes/Using-Rqt-Console/Using-Rqt-Console`) + +* 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:`/Get-Started/Installation/RMW-Implementations/Working-with-multiple-RMW-implementations`. + +Related content +--------------- + +* :doc:`../../Contributing` +* :doc:`Triaging-an-issue` + +FAQs +---- + +TBC diff --git a/source/The-ROS2-Project/Contributing/Contributing-to-code/Triaging-an-issue.rst b/source/The-ROS2-Project/Contributing/Contributing-to-code/Triaging-an-issue.rst new file mode 100644 index 00000000000..7cc26eca0fd --- /dev/null +++ b/source/The-ROS2-Project/Contributing/Contributing-to-code/Triaging-an-issue.rst @@ -0,0 +1,77 @@ +Triaging an issue — how-to +========================== + +Issue triage helps ROS contributors turn incoming bug reports and enhancement requests into clear, actionable work. +This article explains how to find, check, reproduce, assign, and label issues in ROS repositories. +With this information, you'll be able to route issues to the right place, with correct information, and prepare them for work by developers. + +**Area: community | Content-type: how-to | Experience: beginner, intermediate, expert** + +.. contents:: Table of Contents + :depth: 2 + :local: + +Summary +------- + +We welcome anyone to triage issues. + +* **Code issue trackers**: in a repository under the `ROS organisation `__ or elsewhere on GitHub. +* **Documentation issue tracker**: `ROS documentation repository `__. +* **Catch-all issue tracker**: `top level ROS repository `__. + +Prerequisites +------------- + +There are no prerequisites. + +Steps +----- + +1 Finding an issue to triage +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +We encourage contributors to look at incoming issues on ROS repositories and triage the problems that users are having: + +* To find code issues for triage, review the issues list of a repository under the `ROS organization `__, for example the issues list in the `ROS CLI repository `__. +* To find documentation issues for triage, review the issues list in the `ROS documentation repository `__. +* If you're not sure where to start, review the issues list in the `top level ROS repository `__. + +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 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 `__ to get help with their question. +#. 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 `__). +#. If the issue appears to be a valid but lacks sufficient details to replicate the environment (for example, the host operating system, platform, RMW implementation, ROS distro, and offending code) please request that author provide additional information. +#. 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, assign and label the issue appropriately to allow work on the issue to begin by a developer. + +#. Assign the issue to the maintainer for the ROS repository in question. +#. Label the issue as a ``bug`` or ``enhancement``, as appropriate. +#. If this issue is a request for a new feature, label the issue with ``help-wanted``. +#. If the reporter has not provided enough information to determine the cause of the problem, label the issue as ``more-information-needed`` and leave a comment for the reporter, including: + + * What you have tried while investigating the problem. + * In what way the information supplied was insufficient. + * Any suggestions you may have about what additional information is needed. + +Related content +--------------- + +* :doc:`../../Contributing` +* :doc:`Reporting-an-issue` + +FAQs +---- + +TBC diff --git a/source/The-ROS2-Project/Contributing/Developer-Guide.rst b/source/The-ROS2-Project/Contributing/Developer-Guide.rst index ff81ca10854..b4863724a6b 100644 --- a/source/The-ROS2-Project/Contributing/Developer-Guide.rst +++ b/source/The-ROS2-Project/Contributing/Developer-Guide.rst @@ -271,6 +271,7 @@ Some practices are common to all ROS 2 development. These practices don't affect package quality level as described in `REP 2004 `_, but are still highly recommended for the development process. +<<<<<<< HEAD Issues ^^^^^^ @@ -304,6 +305,8 @@ When filing an issue please make sure to: - Trying with a different RMW implementation. See `this page <../../How-To-Guides/Working-with-multiple-RMW-implementations>` for how to do that. +======= +>>>>>>> bf9db74 (3di | Triaging and reporting an issue (#6901)) Branches ^^^^^^^^