From 6fa317cd1e90bbcdf036da98d6e3a0d2536e6744 Mon Sep 17 00:00:00 2001 From: Keith Kirkwood Date: Mon, 1 Jun 2026 16:57:31 +0100 Subject: [PATCH 1/3] OPENR-98: Create article for triaging an issue --- .../How-To-Guides/Core-maintainer-guide.rst | 16 ----- source/The-ROS2-Project/Contributing.rst | 1 + .../Contributing/Contributing-to-code.rst | 8 +++ .../Reporting-an-issue.rst | 4 ++ .../Triaging-an-issue.rst | 62 +++++++++++++++++++ 5 files changed, 75 insertions(+), 16 deletions(-) create mode 100644 source/The-ROS2-Project/Contributing/Contributing-to-code.rst 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/How-To-Guides/Core-maintainer-guide.rst b/source/How-To-Guides/Core-maintainer-guide.rst index c740e2c58fa..90f0892a3f1 100644 --- a/source/How-To-Guides/Core-maintainer-guide.rst +++ b/source/How-To-Guides/Core-maintainer-guide.rst @@ -158,22 +158,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.rst b/source/The-ROS2-Project/Contributing.rst index e775d07cc8f..1ea887b817e 100644 --- a/source/The-ROS2-Project/Contributing.rst +++ b/source/The-ROS2-Project/Contributing.rst @@ -70,6 +70,7 @@ Development Guides Contributing/Build-Farms Contributing/Windows-Tips-and-Tricks Contributing/Contributing-To-ROS-2-Documentation + Contributing/Contributing-to-code What to work on ^^^^^^^^^^^^^^^ diff --git a/source/The-ROS2-Project/Contributing/Contributing-to-code.rst b/source/The-ROS2-Project/Contributing/Contributing-to-code.rst new file mode 100644 index 00000000000..a63fa5e489c --- /dev/null +++ b/source/The-ROS2-Project/Contributing/Contributing-to-code.rst @@ -0,0 +1,8 @@ +Contributing to code +==================== + +.. toctree:: + :maxdepth: 1 + + Contributing-to-code/Triaging-an-issue + Contributing-to-code/Reporting-an-issue 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..33c1cf164c0 --- /dev/null +++ b/source/The-ROS2-Project/Contributing/Contributing-to-code/Reporting-an-issue.rst @@ -0,0 +1,4 @@ +Reporting an issue — how-to +=========================== + +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..da8a2f8b30b --- /dev/null +++ b/source/The-ROS2-Project/Contributing/Contributing-to-code/Triaging-an-issue.rst @@ -0,0 +1,62 @@ +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 +------- + +* **Documentation issues list**: `ROS documentation repository `__. +* **Code issues lists**: in a repository under the `ROS organisation `__. +* **Catch-all issues list**: `top level ROS repository `__. + +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 documentation issues for triage, review the issues list in the `ROS documentation repository `__. +* To find code issues for triage, review the issues list of a repository under the `ROS organisation `__, for example the issues list in the `ROS CLI repo `__. +* If you're not sure where to start, review the issues list in the `top level ROS repository `__ for triage. + +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`. + +#. 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 repo it has been raised in, transfer the issue to the appropriate ROS repository (`see the GitHub documentation for guidance `__). +#. 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. + +#. Assign the issue to the appropriate developer 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``. + +Related content +--------------- + +* :doc:`/The-ROS2-Project/Contributing` + +FAQs +---- + +TBC From 1aa5e82298ade7fe74465c6d7e8c480925c01b78 Mon Sep 17 00:00:00 2001 From: Keith Kirkwood Date: Thu, 4 Jun 2026 16:41:28 +0100 Subject: [PATCH 2/3] OPENR-146: Create article for reporting an issue and update triaging --- source/Contact.rst | 46 ------- .../Reporting-an-issue.rst | 124 ++++++++++++++++++ .../Triaging-an-issue.rst | 28 ++-- .../Contributing/Developer-Guide.rst | 33 ----- 4 files changed, 142 insertions(+), 89 deletions(-) diff --git a/source/Contact.rst b/source/Contact.rst index e8d72b9464a..1bb418a4409 100644 --- a/source/Contact.rst +++ b/source/Contact.rst @@ -33,52 +33,6 @@ If you see an issue on `Robotics Stack Exchange ` and come across an instruction that doesn't work on your system, -you can open an issue in the `ros2_documentation `__ repo. - -You can search for individual ROS 2 repositories on `ROS 2's GitHub `__. - -Before opening an issue, check if other users have reported similar issues by searching across the ros2 and ament GitHub organizations: `example search query `__. - -Next, check `Robotics Stack Exchange `__ 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 `__ 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 `__. -* 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 ------------- 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 index 33c1cf164c0..f6f23d1f213 100644 --- 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 @@ -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 `__. +* **Code issues lists**: in a repository under the `ROS organisation `__. +* **Catch-all issues list**: `top level ROS repository `__. + +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 `__ repo. + +You can search for individual ROS repositories on `ROS GitHub `__. + +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 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 `__ 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 ` 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 `__. +* 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 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 index da8a2f8b30b..68293596cc4 100644 --- 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 @@ -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 `__. -* **Code issues lists**: in a repository under the `ROS organisation `__. -* **Catch-all issues list**: `top level ROS repository `__. +* **Code issue trackers**: in a repository under the `ROS organization `__. +* **Documentation issue tracker**: `ROS documentation repository `__. +* **Catch-all issue tracker**: `top level ROS repository `__. + +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 `__. -* To find code issues for triage, review the issues list of a repository under the `ROS organisation `__, for example the issues list in the `ROS CLI repo `__. -* If you're not sure where to start, review the issues list in the `top level ROS repository `__ for triage. +* 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 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 `__ 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 `__). +#. 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 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 ---- diff --git a/source/The-ROS2-Project/Contributing/Developer-Guide.rst b/source/The-ROS2-Project/Contributing/Developer-Guide.rst index 7296ea2806f..ad08ac3bb05 100644 --- a/source/The-ROS2-Project/Contributing/Developer-Guide.rst +++ b/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 `_, 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 `__. - 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 ` 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 ^^^^^^^^ From 231516314929e01cedc8c484fc894cb9b9948345 Mon Sep 17 00:00:00 2001 From: Keith Kirkwood Date: Thu, 11 Jun 2026 14:56:35 +0100 Subject: [PATCH 3/3] OPENR-146: Fix link issue for linter and add sentence to summary --- .../Contributing/Contributing-to-code/Reporting-an-issue.rst | 2 +- .../Contributing/Contributing-to-code/Triaging-an-issue.rst | 2 ++ 2 files changed, 3 insertions(+), 1 deletion(-) 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 index f6f23d1f213..5c64955b040 100644 --- 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 @@ -36,7 +36,7 @@ You can search for individual ROS repositories on `ROS GitHub `__. +#. 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 appropriate repository's issue tracker. 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 index 68293596cc4..821e875ca2d 100644 --- 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 @@ -14,6 +14,8 @@ With this information, you'll be able to route issues to the right place, with c Summary ------- +We welcome anyone to triage issues. + * **Code issue trackers**: in a repository under the `ROS organization `__. * **Documentation issue tracker**: `ROS documentation repository `__. * **Catch-all issue tracker**: `top level ROS repository `__.