Skip to content

Maintain this handbook

Refresh source evidence

Record branch/commit for each component and compare the installed release with the working source. Use current ROS 2 branches for platform behavior. Inspect Dockerfile package selection, actual startup scripts, CI outputs and runtime configuration when source structure changes.

From the documentation directory:

python3 scripts/inventory.py
python3 scripts/ros_reference.py
python3 scripts/cli_reference.py
python3 scripts/api_contracts.py
python3 scripts/ros_callbacks.py
python3 scripts/config_reference.py
python3 scripts/coverage.py
python3 scripts/audit_contracts.py
.venv/bin/mkdocs build --strict
python3 scripts/check_site.py

The generators do not start services or operate hardware. Parameter/delegate indexes use static analysis and cannot resolve every dynamic schema/name. Refresh the human-written behavior guides as well as generated declarations.

Review a service/API change

Check effective route prefix/method, parameters/models/defaults, validation/errors, response forms, auth/exposure, side effects, persistence, concurrency, timeout/cancellation and streaming lifecycle. Update client examples and related UI instructions. Use installed OpenAPI as an additional comparison where safe, not as a substitute for WebSocket/ROS behavior documentation.

For ROS changes compare generated interface definitions with the exact CMake build list. For UI changes inspect actual controls, disabled/pending states, confirmation behavior, keyboard/mobile behavior and backend calls. Add a workflow mapping to scripts/coverage.py for a new page.

Validate and publish

Strict build checks documentation structure; built-link checks validate generated paths/anchors. Common credential scanning is only a first pass: review public content for private operational data and never upload source credentials/media. Preview representative long references, tables, diagrams, search and compact layout.

Use the deployment runbook and release script. Verify public HTTPS and retained rollback before recording publication as successful. Keep deployment evidence separate from robot hardware/provider acceptance.