Clarify distinction between examples, demos, tutorials

[emersonknapp]

The README nor repository description makes their intended purposes clear. Or at least, a separation of their purpose.

demos README:

This repository contains source code for demos mentioned in the official ROS 2 documentation Tutorials.

examples README

To see some of these examples in use, visit the ROS 2 Tutorials page.

It seems that they partially or totally overlap. When making new documentation/tutorials/example code, it's unclear which repo that should go into.

Criteria to close this issue would be either of:

• the distinction is dissolved and the repos are merged into one, OR
• or the distinction is clarified and added at minimum to the README

[wjwwood]

Well, we also had ros2/tutorials (https://github.com/ros2/tutorials) at one point, which was supposed to be for tutorials, but we've sort of abandoned that for now.

The original logic (as I remember it) was this:

• ros2/demos:
  • demonstrations of capabilities (often used early on to prove to ourselves that something new was working), not a copy-paste ready example and not for education
  • e.g. show that a pointer can be preserved in intra-process comms (https://github.com/ros2/demos/tree/rolling/intra_process_demo)
  • was built and tested on every change of the core and had comprehensive automated tests
• ros2/examples:
  • a cookbook of ready to copy-paste examples that are a good starting point for a variety of things but do not have lots of comments (because they're bad for copy-paste) and little-to-no extra material with them that explains them, they would be somewhat self-evident
  • e.g. c++ node with subscription that uses std::bind (https://github.com/ros2/examples/blob/rolling/rclcpp/topics/minimal_subscriber/member_function.cpp)
  • was built on every change, but lacked automated tests in most cases to keep things simple for copy-paste
• ros2/tutorials:
  • code that is heavily commented (with tags to make the snippets of the tutorial extractable, like we had in ROS 1 tutorials) and was integrated into step by step guides (tutorials), equivalent of ROS 1's ros/ros_tutorials repo
  • e.g. of the tags in ROS 1 that I had hoped we'd migrate over once we had documentation more figured out: https://wiki.ros.org/ROS/Tutorials/WritingPublisherSubscriber%28c%2B%2B%29#roscpp_tutorials.2FTutorials.2FWritingPublisherSubscriber.The_Code which referenced -> (see the // %Tag syntax) https://raw.githubusercontent.com/ros/ros_tutorials/kinetic-devel/roscpp_tutorials/talker/talker.cpp
  • these would be built and tested, with comprehensive automated tests like the demos as it was very important that the tutorials kept working as expected

I think ros2/tutorials was abandoned because we didn't have anyone working on the official tutorials at the time, and despite the rationale above, when we got around to the tutorials no one wanted to add more code and maintain ros2/tutorial (my recollection, but I could be misremembering). Which I think is a shame personally, because I think the above rationale for each repo makes sense.

Ideally, in my opinion, we'd start to get rid of demos and either just have examples with a few of the examples purpose built to be used in tutorials, or resurrect ros2/tutorials and use that as the place where tutorial code lives and keep the examples/cookbook separate. Maybe also rename it to ros2/cookbook as I think that implies better what its purpose is. But those are just my thoughts on what we should do if we were starting from scratch, and I don't know if it would be worth the disruption at this point.

More to your specific question, demos (specifically demo_nodes_cpp and _py) became what we used for tutorials, and examples was meant to stay as a cookbook and not be used in tutorials, but then people started doing that anyways. And so now both contain some stuff used in tutorials, but neither is used for tutorials exclusively.

[fujitatomoya]

@wjwwood @emersonknapp in waffle meeting, we decided to take this to next PMC meeting agenda.

[ros-discourse]

This issue has been mentioned on ROS Discourse. There might be relevant details there:

https://discourse.ros.org/t/ros-pmc-minutes-for-april-8-2025/43138/1

[emersonknapp]

I have an action item from the PMC meeting to write a concrete proposal for what to change, so that we can discuss here and agree on actions.

I will try to get that proposal here before tomorrow's PMC but if I can't, we can discuss it at the following one.

[emersonknapp]

My proposal is in regard to the following repositories, which are the existing designated locations for educational materials and sample code:

• https://github.com/ros2/ros2_documentation
• https://github.com/ros2/examples
• https://github.com/ros2/demos
• https://github.com/ros2/tutorials

I agree with @wjwwood 's distinctions laid out above, reiterating in my words as:

1. examples: small self-contained snippets demonstrating correct usage of end-user APIs and features from the core libraries.
   1. should not have much if any commenting, instead aiming to be self-explanatory
   2. should aim to cover the "core API" as much as possible.
   3. conform to best practices to encourage their spread
2. demos: more in-depth explorations of complex features, edge cases, and integration cases
   2. not for education - these are better compared to integration tests
3. tutorials: Archive this repository in favor of containing tutorials within ros2_documentation
4. ros2_documentation: Entrypoint to the documentation, contains
   3. Installation instructions
   4. Information about the ROS 2 project as a whole
   5. High level concepts that are independent of a specific language
   6. Guided tutorials with code

To reach that goal, I identify these action items:

1. Add a clear blurb in each repository's README.md, mentioning what code belongs and does not belong, in that repository, pointing to the others to extend that
2. Migrate most of demo_nodes_cpp and demo_nodes_py from demos to examples, cleaning up where necessary, to get much of the desired API snipped coverage
3. Officially archive tutorials with a note that the content is being maintained at ros2_documentation
4. Add a "tutorials source" space to ros2_documentation repository, with lint & build & test to keep the code generally working
   1. Pull most if not all source snippets out of rst into files in this space, with literalinclude
   2. I think it better to keep tutorial text and code in same repo, so less "PR ballet"

[dvdmc]

Great action @emersonknapp! I will keep this in mind for future ROS Tutorials issues.

• Maybe templates is a keyword for examples that aligns with its objective.
• Should the best practices be explained somehow in ros2_documentation?

[emersonknapp]

• Should the best practices be explained somehow in ros2_documentation?

Yes, I think so 100 percent! First and foremost the concept documentation and tutorials should always demonstrate good practices, as long as it doesn't complicate the code more than necessary for the point being illustrated at the moment.

Then, for more in depth discussion of those best practices, dedicated page(s) makes sense to me.

[dvdmc]

Noted. I also agree that dedicated pages would avoid information overload at early tutorials.

[emersonknapp]

With no major pushback on the action items proposed - I have renamed this issue to track taking those actions