Contributing#
Tests, the docs pipeline, docstring conventions, and what never goes in a commit.
Ground rules#
- No secrets, ever.
.env,.tiny-mcp.env,earth-rovers-sdk/,*.creds.json,.scout_auth.json,.supervisor/,notes.mdare gitignored — keep them that way. Before pushing:git diff origin/main | grep -nEi 'sk-|token=|Bearer [A-Za-z0-9]|psk|PASSWORD|SECRET|BEGIN .*PRIVATE'. - Safety code stays boring. Anything that touches
/controlgoes throughtools/_rover_common.sdk_post(clamp, auto-stop, thinker gate). Don't add a second path to the wheels. - Docstrings are documentation. The tools reference is generated from the
@tooldocstrings the model itself reads — Google style (Args:,Returns:,Examples:). Fix the docstring, not the page.
Tests#
make test # pytest tests/
pytest tests/test_personas.py -q # supervisor client + flags
pytest tests/test_episode_index.py -q # recorder sealing + repair
pytest tests/test_tiny_mcp.py -q # fleet bridge guards
pytest tests/test_docs.py -q # docs drift: every env var / tool / route documented, no secrets in website/
In the image (pytest is not installed there): docker run --rm -v $PWD:/src -w /src --entrypoint sh scout:slim -c 'pip install -q pytest && pytest -q'.
The docs site#
pip install -r requirements-docs.txt
mkdocs serve # http://127.0.0.1:8000 — regenerates reference pages on every build
mkdocs build --strict # what CI runs; broken links fail the build
- Source lives in
website/(docs/is the cockpit's frontend).mkdocs.ymlsetsdocs_dir: website. website/hooks/gen.pyrunsscripts/tooldoc.py,scripts/envdoc.py,scripts/routedoc.pybefore each build and splices their output between<!-- gen:… -->markers, soreference/tools/*,reference/env.mdandreference/api.mdcan't rot.- Give a new env var a one-line purpose in
scripts/envdoc_notes.py; a new route a note inscripts/routedoc_notes.py. .github/workflows/docs.ymlbuilds strictly and deploys to GitHub Pages on every push tomainthat touches the site or the code it is generated from.
Style#
Python 3.12, type hints where they help, emoji log prefixes are a house style (🛞 🎬 🧠 🌉 📷). Keep tools small: one HTTP hop
to the SDK, clear failure text — the model reads your error messages.