Add initial design documents#1
Conversation
lsy3
force-pushed
the
docs/initial-design-proposal
branch
from
84ecd9e to
df9de93
Compare
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>
lsy3
force-pushed
the
docs/initial-design-proposal
branch
from
df9de93 to
0450557
Compare
- 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>
emersonknapp
left a comment
emersonknapp
left a comment
There was a problem hiding this comment.
Some comments from our discussion today.
- 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>
lsy3
force-pushed
the
docs/initial-design-proposal
branch
from
1719062 to
fc02a8c
Compare
Signed-off-by: Luke Sy <sylukewicent@gmail.com>
alistair-english
left a comment
alistair-english
left a comment
There was a problem hiding this comment.
this is much better to me (a good length!), and i think its worth having something in the repo as a starting point
|
|
||
| ### Key Insights | ||
|
|
||
| Three key insights drive the design: |
There was a problem hiding this comment.
I don't really understand the significantce of the first two - are they worth the words?
|
|
||
| ```yaml | ||
| schema_version: "1.0" | ||
| node: |
There was a problem hiding this comment.
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
left a comment
emersonknapp
left a comment
There was a problem hiding this comment.
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
4 participants
Summary
Founding design documents for the rosgraph project:
docs/MANIFESTO.md— project direction: why, what, howdocs/ROSGRAPH.md— technical proposal: problem statement, prioritised components, key insights, and example schemadocs/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
interface.yamland what the tooling produces from it