Contributing and conventions

Refer to the root CONTRIBUTING.md for setup, testing, pull requests, and DCO sign-off. Refer to AGENTS.md for the architecture and change constraints used by humans and coding agents. Refer to Documentation style for requirements governing customer-facing Markdown and reStructuredText. Refer to DEPENDENCIES.md for the package dependency map.

For a Python change:

uv --config-file uv.toml sync --project <affected-project>
uv --config-file uv.toml run --project tests pytest <affected-test-files>
uv tool run ruff check <changed-python-files>

Public Python references are generated from each enrolled module’s literal __all__, declarations, annotations, defaults, and docstrings. An API-only change therefore updates the code, its co-located documentation, and tests; the strict documentation build rejects unresolved or undocumented exports. Update a narrative page when concepts, workflows, operations, or architecture change, and add a migration entry for a breaking change.

The repository-wide README and documentation ownership rules live in the Comments and documentation section of AGENTS.md. Follow that contract instead of introducing another placement rule in a package or sample.

The user-facing command catalog is generated from top-level sample [project.scripts] entries and literal argparse declarations. Keep option descriptions in help= and do not repeat flag tables in narrative pages.

Sample configuration examples live in checked-in YAML and JSON files, with field-level guidance in adjacent YAML comments. The generated catalog enrolls files under a top-level sample’s yaml/ tree and files beside a direct capability subproject, then renders them verbatim. Narrative docs cover only workflows, operational decisions, credentials, and process relationships.

Application-owned projects under apps/ are outside the repository sample and contribution tooling described below. After a pyproject.toml change elsewhere, run uv run --script .github/scripts/generate_dependency_map.py. The pre-commit hook normally regenerates the Python inventory in DEPENDENCIES.md automatically, and CI rejects drift. Do not edit that generated section by hand. Regenerate the affected project’s gitignored uv.lock locally. New source files outside apps/ require an SPDX header; refer to SPDX headers.

The root uv.toml records the repository’s dependency qualification cutoff. Repository CI passes it explicitly to uv, so fresh resolutions ignore package-index artifacts uploaded after that timestamp while normal compatibility ranges stay in package metadata. Standalone nested projects do not always inherit the root file: uv stops upward config discovery at a nearer [tool.uv] table, and most projects define [tool.uv.sources]. Run uv from the repository root with --config-file uv.toml as shown above. To qualify newer dependencies, advance the cutoff in a dedicated change, resolve every project with uv --config-file uv.toml lock --upgrade --project <directory>, and run the full test suite. The generated per-project lockfiles are validation artifacts and remain gitignored. The same change regenerates the committed locks under dependency-manifest/; the pre-commit hook does the Python one when uv.toml is staged.