Contributing

Contribution workflow

• Open an issue before a large change; use an RFC for new ports, config versions, execution capability, model defaults, telemetry, or governance changes.
• Branch from dev and return to dev through review; reviewed release changes are promoted to main.
• Keep pull requests focused and include tests, documentation, changelog notes, security impact, and compatibility notes.
• Sign off every commit with git commit -s — the Signed-off-by trailer is a provenance declaration that you have the right to submit the work under Apache-2.0.
• Never contribute private logs, credentials, employer or client code, confidential runbooks, or copied vendor implementations.

AI-assisted contributions

AI-assisted contributions are welcome. You may use coding assistants, language models, or other AI tools for code, tests, documentation, examples, and review. The human contributor remains fully responsible for the submitted result: you must understand it, verify it, follow the architecture and safety boundaries, run the required checks, remove secrets and private data, and have the legal right to contribute every part under Apache-2.0.

• AI output is not evidence that a change is correct, secure, original, or compatible—your review and the project checks are.
• Follow the repository's structure, patterns, and documented boundaries exactly as you would when writing by hand.
• Briefly disclose material AI assistance in the pull-request description so reviewers understand provenance and review context.
• Do not submit generated, copied, employer-owned, or model-assisted material that you cannot explain and defend.

Local checks

uv sync --all-groups
uv run ruff format --check .
uv run ruff check .
uv run mypy src
uv run python scripts/generate_config_schema.py --check
uv run pytest
uv build

CI runs the same checks, verifies that generated JSON Schemas match the Pydantic contracts, and never makes a live model call. Releases are manually dispatched through GitHub Actions and published with PyPI Trusted Publishing.

Good first contributions

Documentation, error messages, synthetic fixtures, validator tests, CLI polish, and cookbook improvements are good first areas. Sensitive execution and policy work requires deeper design review—start a discussion before writing code there.