ros2 · mergify · Jul 31, 2026
diff --git a/source/Contact.rst b/source/Contact.rst
@@ -33,6 +33,7 @@ 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.
 
+<<<<<<< HEAD
 Issues
 ------
 
@@ -78,6 +79,8 @@ As appropriate, also include your:
 * Bag files and code samples that can reproduce the problem
 * Gifs or movies to demonstrate the problem
 
+=======
+>>>>>>> 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
@@ -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 <https://robotics.stackexchange.com/>`__ .
-
-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
@@ -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
@@ -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 <https://github.com/orgs/ros2/repositories>`__ or elsewhere on GitHub.
+* **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/issues>`__.
+
+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 </First-Steps>` and come across an instruction that doesn't work on your system, you can report an issue in the `ROS documentation repository <https://github.com/ros2/ros2_documentation/issues>`__.
+
+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 <https://github.com/ros2>`__
+* ROS binary packages, found on the `ROS Index <index.ros.org>`__, 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 <https://github.com/ros2/ros2/issues>`__ 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 <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 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 <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
+  * 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
@@ -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 <https://github.com/orgs/ros2/repositories>`__ or elsewhere on GitHub.
+* **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
+-----
+
+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 <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 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 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 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
@@ -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 <https://reps.openrobotics.org/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
 ^^^^^^^^