RFC: The ROS 2 Reference

[onkoe]

Summary

For the past decade, ROS 2 has built itself up progressively in the footsteps of the original ROS. Over time, the community has collected more and more examples and beginner-level information into its documentation site, docs.ros.org.

Despite this great community resource, ROS 2 lacks a critical form of documentation - a technical, expert-level ROS 2 Reference set of documentation. This issue attempts to describe the need for such a resource, how it might look, and what parts of the community it might attempt to serve.

What is a "reference"?

I'm most familiar with Rust, so I'll start this off with an example. When a user decides to learn Rust, they'll use the free online book, The Rust Programming Language. However, people who want to understand the language at an expert level would use The Rust Reference.

Does ROS 2 have anything similar? (plus an example)

In short: no.

Here's a quick mapping of the ROS 2 and Rust docs:

• ✅ Rust's std library docs <=> ROS 2's rclpy docs
• ✅ The Rust Programming Language (online book of beginner docs) <=> ROS 2 Documentation
• ❌ The Rust Reference <=> ...nothing.

ROS 2 doesn't have technical documentation anymore. The Wiki is a decade out-of-date, and design.ros2.org is almost a half-decade unmaintained. These resources are now unusable for creating bindings, expanding the ecosystem, and contributing to various internal ROS 2 components/projects.

What defines a reference?

The ROS 2 Reference would have the "final say" on how a specific feature, subject, or concept would behave in ROS 2 - even within non-rcl implementations of ROS 2.

In other words, it would describe the behavior of the various concepts in ROS 2. So, to be clear, a reference would do two things:

1. Define invariants (assumptions required for correct behavior)
2. Discuss behavior (how a concept will behave)

...for each important ROS 2 concept.

Why would we want a ROS 2 Reference?

In essence, ROS 2 has a lack of highly technical users (known as "expert-level" users). These are people who understand ROS 2 in and out - they could expand the ecosystem, rewrite/contribute to rcl and other ROS 2 implementations, and write technical documentation.

Most of the existing experts were around for ROS 2's conception and development, while most others develop with ROS 2 in industry. Without primary knowledge of the developments taking place since design.ros2.org went unmaintained, it's nearly impossible to become an expert.

A ROS 2 Reference would give everyday users (and potential contributors) a well-trodden path to expertise.

Who would benefit from reference documentation?

There are two primary beneficiaries: new experts in ROS 2, and the community as a whole.

New experts

With a reference, anyone can now become an expert in ROS 2. These folks would gain a deeper understanding of the project, often empowered to tackle ecosystem-wide problems through novel solutions.

Researchers would be able to make better assumptions about ROS 2 as a project, and companies/organizations could make better assumptions about their products and plans.

ROS 2's wider community

The community would benefit from higher levels of correctness in tooling, more contributors to the ecosystem, and more knowledgeable folks within the community.

FAQ

So... is this a specification?

No. The Reference would likely be more casual. You wouldn't see words like "SHOULD" and "MUST" everywhere - it's not a direct set of instructions for implementation.

Instead, it would attempt to describe how stuff behaves in ROS 2. (it would still be helpful for alternative implementations, though!)

How is this different from our existing Concepts documentation?

The Concepts section in the existing documentation more describes footguns and reminds users how things work in general.

They don't serve as a reference; it's more like a glossary (or a list of keywords).

Would the Reference be for beginners?

No, unless they're roboticists who already understand stuff like ZeroMQ, have heavy robotics experience, and largely comprehend the needs of the robotics ecosystem at scale.

However, it'd be helpful for users with intermediate proficiency who are looking to understand the low-level aspects of ROS 2 to a much higher degree.

What would be in the Reference specifically? What would we start with writing?

In my view, we should stick to writing about the basics at first. Things like nodes, interfaces, and interface destinations (topics, services, and actions) are rather under-specified at the moment. Describing their exact behavior would beef these up - we'd see more ecosystem-wide development.

I'd also love to see more information about launch files and the colcon build system. Both of these are massively underdocumented at present, and ROS 2 has special behavior linked to each. Largely, understanding this behavior is left to users, which leads to widespread misunderstandings and uncertainty.

Here's a short list of things that really should be specified:

• Nodes
• Parameters
• Interfaces
• Interface destinations
  • Overrides and syntax
• Rosbag2
• DDS, Zenoh, and how middleware behaves
• IDL
• QoS
  • Overrides and syntax
• The ros2 CLI
• Lifecycle (managed) nodes
• colcon, build systems, and project layout
  • We should discuss build/ and install/ + how they are used in the CLI
  • Source scripts
  • System dependencies, rosdep, and colcon
• Releases
  • The meaning of a major version
  • Notes on compatibility and "ABI"
  • "Snapshots"

There are likely other things to be added here - having "a reference" is nice for anything that has behavior. Nav2 could have a reference, Gazebo could, etc.

However, it's best to focus on core ROS 2 concepts, in my view.

[DLu]

I think this could be a valuable aspect to the ROS documentation, however, I'm not sure I personally see the complete vision yet, and there's a couple claims I'd push back on.

The ROS 2 Reference would have the "final say" on how a specific feature

The Reference would likely be more casual. You wouldn't see words like "SHOULD" and "MUST" everywhere - it's not a direct set of instructions for implementation.

These two sentences seem to be at odds with each other. Can you clarify what you were thinking?

In essence, ROS 2 has a lack of highly technical users (known as "expert-level" users). These are people who understand ROS 2 in and out - they could expand the ecosystem, rewrite/contribute to rcl and other ROS 2 implementations, and write technical documentation.

I guess its how you define "user" but IMHO, experts do exist, they're just all writing/maintaining the core, and some spend less time than the community would prefer writing documentation. My uncited, biased impression is that, compared to ROS 1, there is a greater distance between the core maintainers and the users building complex robotics systems.

---

Just to expand on one idea, let's take the ROS 2 reference for Nodes. What would it contain? The tutorials already have a bunch of examples in different languages. I can also think of a bunch of "styles" for writing nodes, i.e. in C++ either extending the node class, or keeping a NodePtr as a protected variable. Neither of those is the "final say" or invariants.

---

Just to put a final point on it, I like the idea, but I don't personally see how to start writing it (yet).

[christophebedard]

I also don't fully understand the idea. Or, rather, I don't see how that's different from asking for more/better documentation, which I agree with.

Here's a short list of things that really should be specified:

A lot of that is already documented: what's missing, exactly? Like David asked above, what would the content look like, in practice? Are you asking (in part) for a better structure, like the nice structure/ToC of the Rust Reference? Could part of the complexity with transposing this idea from Rust to ROS 2 come from the fact that Rust is a language (which allows documentation to be a lot more structured), whereas ROS 2 is a framework (not just a library/API)?

Overall, and looking at the list, I agree with the statement that the documentation could/should be better, i.e., cover more. I also like that the Rust Reference is explicitly not an introduction to the (Rust) language, which you also mentioned.

For example, someone asked in Discord today about documentation on the rmw implementation: specifically documentation about implementing the rmw interface. There's a design article and a concepts page, but they don't really dive deep enough. I wrote an rmw implementation myself, so I know what's missing.

There's also the launch system. I do see the need for a full "reference:" list of actions and their arguments (ros2/launch_ros#404), list of substitutions and what they do, the difference between actions and substitutions, etc. That would probably be very useful to (non-beginner) users. I'm guessing this is what you want, but I find it hard to apply to other things like nodes.

[christophebedard]

My uncited, biased impression is that, compared to ROS 1, there is a greater distance between the core maintainers and the users building complex robotics systems.

I think that is true. I've had the same (introspective?) feeling lately.