3di | Triaging and reporting an issue#6901
Conversation
|
|
||
| Communication issues may be specific to the underlying ROS middleware being used. | ||
|
|
||
| * **ROS client library** |
There was a problem hiding this comment.
Question for the community: does knowing which ROS client library when you report an issue necessarily mean you know which package the issue is with? And hence which issue tracker to use for the report? If so, that will be a helpful note up in section 1.
I know the general definitions of these terms, but not what the exact relationship is within the ROS world.
My best guess would be that all client libraries are packages, but not all packages are client libraries.
There was a problem hiding this comment.
please have a look at my comment above.
i think what we need to explain here is that users and developers are expected to use the issue template when they are registering the issue. that should include the required information to fill in. in this way, we do not need to come back here to update the documentation when the template is changed or update in the future.
fujitatomoya
left a comment
fujitatomoya
left a comment
There was a problem hiding this comment.
i have a couple of minor comments on this PR.
i do understand that this PR is trying to restructure the tree but it would be nice to fix at the same time. btw, my comments should not block this PR.
|
|
||
| Issues are more likely to be resolved if others can reproduce them easily. | ||
|
|
||
| #. Include the following information: |
There was a problem hiding this comment.
if this is the requirement for issue header, we could use the github issue teamplate instead. that should apply this format to register the issue. for example, https://github.com/ros2/ros2_documentation/tree/rolling/.github/ISSUE_TEMPLATE (ros2_ducomentation template) and https://github.com/ros2/.github/tree/main/.github/ISSUE_TEMPLATE (ros2 organization scope template unless there is no repository specific template)
|
|
||
| Communication issues may be specific to the underlying ROS middleware being used. | ||
|
|
||
| * **ROS client library** |
There was a problem hiding this comment.
please have a look at my comment above.
i think what we need to explain here is that users and developers are expected to use the issue template when they are registering the issue. that should include the required information to fill in. in this way, we do not need to come back here to update the documentation when the template is changed or update in the future.
kscottz
left a comment
kscottz
left a comment
There was a problem hiding this comment.
This is a good start but there's probably some more context that we could provide to make it better. Since this is geared towards new users there's a couple of things that we're failing to mention / cross reference in the documentation, including:
- How to figure out what ROS package is causing the issue and where to find that package's source code repository.
- How to use
ros2 doctorto report your system configuration. - As @fujitatomoya mentioned, how to use the report template.
- Where to find the appropriate log files in ROS.
| ------- | ||
|
|
||
| * **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>`__. |
There was a problem hiding this comment.
This could probably be more clear. Issues should be reported in the Github repository for the repository in which the error occurred (generally the last file listed in the stack trace).
| 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>`__. |
There was a problem hiding this comment.
This should be expanded. Roughly we have three buckets where things live.
- Core ROS 2 -> github.com/ros
- A ROS binary package that can be found on index.ros.org (and points to the appropriate Github repo)
- A source ROS package that is located somewhere on Github.
There was a problem hiding this comment.
We probably need a section before this on identifying the correct place to report an 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. | ||
|
|
There was a problem hiding this comment.
@fujitatomoya I would be curious to hear your opinion here, but I think generally new users should be using ros2 doctor when reporting issues. We already have documentation on how to use it. There's no harm in doing so and I think it would go a long way towards helping users help themselves.
| * 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 |
There was a problem hiding this comment.
New users struggle with finding where the appropriate log files live. We probably want to include information on that here. We do have a general page about logging here but I just read through it but at no place in that document do we mention the default log directory on each platform (e.g. /var/log/ros... on Linux ) or specify how to find the most recent logs and read them (e.g. tail -100)
There was a problem hiding this comment.
| 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>`__). |
There was a problem hiding this comment.
| #. 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 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 appropriately replicate it (e.g. the host operating system, platform, RMW implementation, ROS distro, and offending code) please request that author provide additional information, |
That's not quite right, but you get the idea.
|
|
||
| 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. |
There was a problem hiding this comment.
How are new users supposed to know this information? Generally they should tag the maintainer, but that isn't always apparent.
3 participants
Description
Refactor/consolidation and partial rewrite of content from several sources to create new articles for Triaging an issue, and Reporting an issue under Contributing section.
Related to: ros2/ros2#6828
Did you use Generative AI?
No
Additional Information
Documentation updates from 3di Information Solutions, agreed with Geoff and Tully.