# Contributing

This is the short version. The full policy is in the root
[`CONTRIBUTING.md`](https://github.com/whitecircle/halo/blob/872a3e4284ef3a533c18b651f91b76adcbdcf306/CONTRIBUTING.md).

Bug reports, proposals and focused pull requests are welcome. A code change
needs an accepted issue and a maintainer's `/approve @your-handle` on it before
any PR, and PRs from unapproved contributors are closed automatically. The
issue templates, the gate and working from a fork are in the full policy; report
security issues privately ([`SECURITY.md`](https://github.com/whitecircle/halo/blob/872a3e4284ef3a533c18b651f91b76adcbdcf306/SECURITY.md)).

## Own your code

You must understand and own every line you submit. Writing code with AI is fine:
Halo itself is built with AI, and the images ship [skills](https://whitecircle.com/halo/docs/ai-tooling.md) that
teach an agent this codebase. Submitting code you can't explain is not. The PR
template asks you to disclose the scaffold and models you used.

## Checklist

1. Issue, approval, then a focused PR. Keep the diff under about 2,000 lines.
2. Pull or build the image and run the gates:

   ```bash
   make lint && make format   # host
   make docs                  # host (stdlib Python 3.12+): links, anchors and code references
   make seed-hf-cache         # image: Hub configs and tokenizers the CPU tests read
   make test-cpu              # image, no GPU needed
   make test-gpu-core         # image, for GPU-affecting changes
   ```

   Re-run `make seed-hf-cache` when `tests/common/models.py` or `examples/` add
   a Hub repo. Hosted CI runs only lint, the convention tests and the docs checks,
   so report your test results in the PR. A change to a path in
   `.github/sensitive-paths` also needs the `sensitive` label from a maintainer.
3. Ship tests that fail when the behavior breaks. Smoke-only tests and
   `assert x is not None` don't count. See the test guide in
   [`agent-docs/contributing/`](https://whitecircle.com/halo/docs/agent-docs/contributing.md) ↗.
4. Sign every commit (SSH or GPG), forks included. PRs are squash-merged, and
   GitHub won't merge one while any commit lacks a verified signature. Setup and
   re-signing are in [`CONTRIBUTING.md`](https://github.com/whitecircle/halo/blob/872a3e4284ef3a533c18b651f91b76adcbdcf306/CONTRIBUTING.md).
5. Never commit secrets, `.env` or keys.

Building images, running tests and the docs tooling are covered in
[Development environment](https://whitecircle.com/halo/docs/agent-docs/contributing/development-environment.md) ↗.
