# Contributing to ablate

Thanks for the interest. This is a young project — read `docs/00-verdict.md`
through `docs/12-open-questions.md` before proposing anything structural;
most "why not just X" questions are already answered there, with the
reasoning kept in `docs/adr/`.

## Setup

```bash
git clone https://github.com/ablate-dev/ablate
cd ablate
uv venv
uv pip install -e ".[dev]"
source .venv/bin/activate
```

## Before you open a PR

```bash
uv run pytest -q       # 51+ tests, all against real git repos, not mocks
uv run ruff check .
```

CI runs both on every PR across Python 3.11–3.13.

## What a good contribution looks like here

- **Tests exercise real git, not mocks of it.** The existing suite creates
  actual git repos in `tmp_path` fixtures — worktree operations and diff
  assertions have real failure modes a mock can't reproduce. Follow that
  pattern.
- **No LLM judge, anywhere.** This is a hard architectural line
  ([ADR-0004](docs/adr/0004-no-llm-judge.md)), not a "not yet." Every
  assertion type must be a deterministic check a human could run by hand.
- **Statistics claims need the honesty constraints respected.** Point
  estimates without confidence intervals are not new features — see
  `docs/05-statistics.md` and `docs/08-surfaces.md`'s design rules before
  touching the report renderer.
- **Follow the milestone order** in `docs/09-milestones.md` unless you have
  a specific reason not to — M2 (statistics) is the current frontier.

## Reporting bugs

Open an issue with the exact `ablate` command, the repo it was run against
(or a minimal reproduction), and — if it's a trial-execution bug —
`--keep-worktrees` output if you can share it.

## Commit messages

Explain *why*, not *what* — the diff already shows what changed. Squash-merge
is fine; a clean single-purpose commit is better than a tidy history for its
own sake.
