Add initial design documents by lsy3 · Pull Request #1 · ros-tooling/rosgraph

lsy3 · 2026-02-22T18:33:29Z

Summary

Founding design documents for the rosgraph project:

docs/MANIFESTO.md — project direction: why, what, how
docs/ROSGRAPH.md — technical proposal: problem statement, prioritised components, key insights, and example schema
docs/FAQ.md — audience-organized FAQ covering 9 perspectives (new ROS dev, AI-assisted dev, eng lead, safety engineer, nav2/MoveIt user, skeptic, package maintainer, educator, embedded dev)

Context

These documents are the starting point for WG discussion. The PR serves as the review and acceptance process — please comment inline.

Key sections in ROSGRAPH.md

Executive Summary — the problem and key gaps in the ecosystem
Components — prioritised list: Node Spec (NoDL), Code Generation, Runtime Discovery, Unit Testing, Graph Analysis, Documentation
Key Insights — three design principles driving the approach
Example — minimal interface.yaml and what the tooling produces from it

Three founding documents for the rosgraph project: - MANIFESTO.md: project direction (why, what, how) - ROSGRAPH.md: full technical proposal (schema, architecture, phasing) - FAQ.md: audience-organized FAQ covering 9 perspectives Signed-off-by: Luke Sy <sylukewicent@gmail.com>

- FAQ: reduce from 880 to ~360 lines, add General section with cross-cutting questions, keep 2-3 essential per audience - FAQ: fix all PROPOSAL.md cross-references to ROSGRAPH.md - FAQ: add launch file / param config convergence question - ROSGRAPH §3.2: add "Toward a single source of truth" note on system.yaml replacing launch files and parameter configs - ROSGRAPH §12: remove resolved questions section (internal notes) Signed-off-by: Luke Sy <sylukewicent@gmail.com>

alistair-english · 2026-03-03T20:21:37Z

docs/MANIFESTO.md

+
+## Why
+
+Robotics engineers spend too much time on ROS plumbing — writing boilerplate, debugging invisible wiring, and keeping launch files in sync with code — instead of building their application.


as systems get larger, they become harder to reason about. The lack of a "well defined" interface (topic, service, action) contracts makes this even harder. It also excludes any ability to have automated tools to give leverage over this problem

Addressed — incorporated into the MANIFESTO Why section alongside Emerson's comment. The paragraph now covers both the undocumented interfaces point and the scaling/automated tooling angle.

emersonknapp

Some comments from our discussion today.

docs/MANIFESTO.md

emersonknapp · 2026-03-03T20:18:42Z

docs/MANIFESTO.md

+
+## What
+
+A declarative, observable ROS graph. Engineers declare what their system should be; tooling generates the code and verifies the running system matches the spec.


code and entities as needed

Done — updated to "generates the code and entities as needed".

emersonknapp · 2026-03-03T20:31:28Z

docs/ROSGRAPH.md

+covering the four goals of the ROSGraph Working Group:
+
+```
+rosgraph


Seeing this more as specific components that may or may not be wrapped by user interfaces like a CLI:

Node spec

Code generation

Runtime discovery

Node-level unit testing

Graph analysis & comparison (integration-level testing)

Documentation generation

Call out order of importance:

Node Spec (NoDL) most core part of the whole thing.

Then, code generation and runtime discovery are the equal-importance next key components to making that NoDL useful.

nodl-generator takes NoDL input and outputs code for a ROS Client Library.

rclcpp

rclpy

rclrs??

Open question: implementation language for the generator tooling?

Hard requirement: nodl-generator is installable as part of a ROS distro (apt-get install, etc)

Architecture requirement for codegen, sidechannel plugin for other language client libraries - rcljava or whatever

All addressed in the ROSGRAPH rewrite. The proposal now frames these as independent, composable components (not CLI subcommands), ordered by priority:

Node Spec (NoDL)

Code Generation — plugin architecture for additional client libraries (e.g. rcljava), must be distro-installable

Runtime Discovery

Node-level Unit Testing

Graph Analysis & Comparison (integration-level)

Documentation Generation

Also calls out the open question on implementation language for the generator tooling.

- MANIFESTO: add undocumented interfaces problem, update wording - ROSGRAPH: greatly summarise from 1715 to 133 lines - Remove sections 3-12 (architecture, phasing, language choice, etc.) - Remove design principles (redundant with key insights) - Replace CLI subcommand tree with prioritised components - Add codegen requirements (plugin arch, distro-installable) - Condense gap table to bullet list - Clarify discovery vs monitoring distinction Signed-off-by: Luke Sy <sylukewicent@gmail.com>

Signed-off-by: Luke Sy <sylukewicent@gmail.com>

alistair-english

this is much better to me (a good length!), and i think its worth having something in the repo as a starting point

alistair-english · 2026-03-17T05:06:03Z

docs/ROSGRAPH.md

+3. **Runtime Discovery** — introspect a running system and produce NoDL
+   specs from observed nodes. Enables brownfield adoption: point at an
+   existing system, generate `interface.yaml` files for every node, then
+   iteratively refine them. Unlike runtime monitoring (component 5),


i suppose its not the same (one-time vs continuous), but i suspect it will actually be the same thing (continuous monitoring = generate a spec from a running system and check for diffs)

alistair-english · 2026-03-17T05:07:32Z

docs/ROSGRAPH.md

+
+- Node A publishes `/cmd_vel` as `Twist`. Node B subscribes to
+  `/cmd_vel` as `String`. You discover this at runtime — or don't,
+  because the subscriber silently receives nothing.


along this line of thought - refactoring topic names across a system is difficult (e.g. you change your teleop node to produce /cmd instead of /cmd_vel and aren't sure what the downstream implications are)

alistair-english · 2026-03-17T05:08:58Z

docs/ROSGRAPH.md

+
+### Key Insights
+
+Three key insights drive the design:


I don't really understand the significantce of the first two - are they worth the words?

alistair-english · 2026-03-17T05:11:09Z

docs/ROSGRAPH.md

+
+```yaml
+schema_version: "1.0"
+node:


a nitty-gritty schema design thing, but interface.yaml shouldn't have node and package keys - defining the node and package is not the responsbility of the yaml file.

In the chain of responsibility:

package has a -> node has an -> interface.

Interface doesnt look back the other way.

emersonknapp

Looks good, we should move forward. With caveat that I agree with @alistair-english comments. The key insights are a little hard to understand what they're trying to say, may not be necessary. And, the schema proposal may be too much detail here - but it doesn't hurt to have it, called out explicitly as an "illustrative directional example" but not concrete proposal. We will work on the schema itself as focused reviews.

- Add topic rename as a concrete problem example - Reframe discovery vs monitoring as same mechanism, different cadence - Collapse Key Insights to the one load-bearing point (codegen) - Remove node/package keys from interface.yaml example

lsy3 force-pushed the docs/initial-design-proposal branch from 84ecd9e to df9de93 Compare February 22, 2026 18:37

lsy3 force-pushed the docs/initial-design-proposal branch from df9de93 to 0450557 Compare February 22, 2026 18:48

alistair-english reviewed Mar 3, 2026

View reviewed changes

emersonknapp reviewed Mar 3, 2026

View reviewed changes

lsy3 force-pushed the docs/initial-design-proposal branch from 1719062 to fc02a8c Compare March 12, 2026 16:38

Remove FAQ.md to simplify CLI reference maintenance

f27121f

Signed-off-by: Luke Sy <sylukewicent@gmail.com>

lsy3 requested review from alistair-english and emersonknapp March 12, 2026 16:48

lsy3 marked this pull request as ready for review March 12, 2026 16:48

alistair-english approved these changes Mar 17, 2026

View reviewed changes

emersonknapp approved these changes Mar 18, 2026

View reviewed changes


		## Why

		Robotics engineers spend too much time on ROS plumbing — writing boilerplate, debugging invisible wiring, and keeping launch files in sync with code — instead of building their application.


		## What

		A declarative, observable ROS graph. Engineers declare what their system should be; tooling generates the code and verifies the running system matches the spec.

Conversation

lsy3 commented Feb 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Context

Key sections in ROSGRAPH.md

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

emersonknapp left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

alistair-english left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

emersonknapp left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

lsy3 commented Feb 22, 2026 •

edited

Loading