Development Guide¶

This guide is for both humans and agents.

Development environment¶

We use dev container for both local development and CI.

Prerequisites¶

Docker
Dev Container CLI
(Optional) An IDE with dev container support, e.g. VS Code with the Dev Containers extension
All other dependencies are installed in the dev container.

Dev container setup¶

No separate setup is needed. The ./dev.sh script calls devcontainer up automatically, which builds the container image on first run.

Commands¶

The ./dev.sh script runs commands inside the dev container from the host. Omit it if you’re already inside.

Bazel¶

Build¶

./dev.sh bazel build //...

Test¶

./dev.sh bazel test //...

Pytest¶

./dev.sh python -m pytest

Format¶

./dev.sh ./tools/format.sh

To check without modifying (used in CI):

./dev.sh ./tools/format.sh --check

Lint¶

./dev.sh ./tools/lint.sh

Docs¶

Build¶

./dev.sh ./tools/docs.sh

Serve¶

./dev.sh ./tools/docs.sh serve

Code style¶

Python¶

Follow Google Python Style Guide.
Use ruff for formatting and linting.

Bazel¶

Follow BUILD Style Guide.

Doc style¶

We use Sphinx with MyST-Parser (Markdown) and the Furo theme.
Follow Google Markdown Style Guide.
For titles, use Title Case.
For non-title section headings, use Sentence case.
Use plain hyphens (-) instead of em dashes.

Quality checks¶

Before commit, ALWAYS run the following commands and fix any issues you see:

./dev.sh bazel build //...
./dev.sh bazel test //...

./dev.sh ./tools/lint.sh
./dev.sh ./tools/docs.sh

# Run format last so no subsequent edits undo it.
./dev.sh ./tools/format.sh

Commit style¶

Keep the subject line under 72 characters.
Explain why the change is being made.
Describe what has changed at a high level. Don’t repeat what’s obvious in the change itself.
Prefer one commit per logical change. Don’t split into too many tiny commits when they form a single unit of work.
For agents: credit yourself (e.g. using Co-authored-by:) for commits you made.