Start Here
This is nano-ros Internals, the book for people who change nano-ros itself. If you want to use nano-ros (write nodes, bring up a board, add a board or an RMW backend from outside the tree), read the nano-ros Book instead. Everything there works from an installed release, while everything here assumes a checkout.
The two books and the records
| You want… | Read |
|---|---|
| To use nano-ros, or to port it to a board, platform, transport or RMW | the nano-ros Book |
| How the tree is built, tested, generated and released | this book |
| Why a decision was made | an RFC in docs/design/ |
| What is being worked on, and its acceptance | a phase doc in docs/roadmap/ |
| A known bug, limitation or piece of tech debt | an issue in docs/issues/ |
The three numbered series are records. This book is narrative: it explains how the parts work and links to the record that decided each one, without copying it.
The books are split by reader, not by topic (RFC-0123). When a subject has a user side and a contributor side, each book has its own page and the two link to each other. For example, the Book’s ROS 2 interop page says what to do, and RMW Internals → Zenoh protocol says how it works.
First hour
- Set up a checkout: Contributing.
- Learn the shape of the system: Architecture, then the repo map.
- Learn the verbs.
justwith no arguments lists about eight, grouped by when you need them, andjust check <name>runs one gate. Build Commands has the full list. - Before you open a pull request, run
just check fast.
Where a new fact goes
When you learn something that will still be true later, file it where the next person will look:
- a design decision goes in an RFC;
- planned work goes in a phase doc;
- a bug or limitation goes in an issue;
- how something works, for contributors, goes on a page of this book;
- how to use something goes on a page of the nano-ros Book.
CLAUDE.md and AGENTS.md at the repo root are routers for coding agents.
They point here and into docs/, and they deliberately hold no design
detail.