Contributing
Use this page as the contributor landing page. It shows the shortest route from local setup to PR handoff, with the deeper validation and maintainer runbooks linked only where they become necessary.
Use this page as the contributor entry point. It shows where to set up locally, how much validation to run, what to include in a PR, and who owns the merge.
1. Set up locally
Start with the Developer Guide for dependency install, model configuration, local startup, and the main local commands.
Keep the validation references nearby:
- choose a validation lane in the Validation guide
- run exact commands from the repository
TESTING.mdrunbook
2. Pick the right validation lane
Run the lightest checks that still cover your change:
| Change type | Start here | Then run |
|---|---|---|
| docs-only copy or nav | this page | uv tool run --with mkdocs mkdocs build --strict |
| Python or runtime behavior | Developer Guide | Validation guide, then the repository TESTING.md runbook if you need deeper coverage |
| Helm, Kustomize, or deploy manifests | Validation guide | manifest checks from the repository TESTING.md runbook |
| end-to-end or alert flow changes | Validation guide | kind or full alert-pipeline flows from the repository TESTING.md runbook |
3. Open or update a PR
Make the PR easy to validate:
- summarize the user-visible change
- list the commands already run
- link the docs or product pages you changed
- note where QA should look for evidence
4. Handoff to QA
QA validates the current PR head after contributor checks are complete.
Your handoff should call out:
- which validation lane you chose
- any artifact paths, screenshots, or logs worth checking
- the exact PR head commit if QA may need to re-run after later fixes
- whether commits changed after any earlier QA sign-off
5. Merge ownership
Contributors do not merge by default. The expected route is:
- contributor opens or updates the PR
- QA validates the current revision
- contributor addresses feedback and requests re-validation if commits changed
- a human reviewer or repo owner performs the final merge
You should not need the Maintainers Guide for the normal contributor route. Use it only when you are handling release or repository-owner responsibilities.