diff --git a/AGENTS.md b/AGENTS.md index 3beccb67..cb9a9cd4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -10,6 +10,21 @@ Part of the RVC ecosystem. **Read [rvc-ecosystem/AGENTS.md](https://github.com/p | Default branch | `main` | | Contribution model | Branch โ†’ PR; direct push to `main` at Peter's discretion | +## What the Toolbox is for + +The Toolbox has three goals, in this order: **pedagogy** (code that is clear and easy to +read, and that follows the explanations in *Robotics, Vision & Control*), **functionality** +(the range of what it covers), and **performance** (speed and memory). + +A faster implementation is welcome alongside a readable one, not instead of it. A change that +gains speed by making the code harder to understand will not be accepted. Nor will a change to +an algorithm that the book explains if the results differ from the book; a restructured +implementation that gives the same results is fine, with a comment pointing to the book +section. New algorithms beyond the book are welcome. + +If your change trades clarity for speed, or changes what an algorithm does, say so in the PR +description and ask first. + ## Notes specific to this repo - Pure Python โ€” no compiled extensions, builds with Hatch (`hatchling`) directly. @@ -28,3 +43,37 @@ Part of the RVC ecosystem. **Read [rvc-ecosystem/AGENTS.md](https://github.com/p - Codacy is wired in (badge + automated PR comments); grade A is the aspiration. Real backlog exists, tracked via `tech-debt`-labelled issues (including a "mypy not in CI" entry) โ€” see ecosystem `AGENTS.md` ยง5 for how that target is framed. +- Type checking: `mypy` (config in `pyproject.toml` under `[tool.mypy]`; run it from the repo + root with no arguments). The package passes with zero errors and must stay that way. It is + not yet run in CI (tracked as Issue 40), so run it yourself before opening a PR. Write + ignores as `# type: ignore[code]` with the specific error code; unused ignores are reported. + Import from the defining submodule (for example `machinevisiontoolbox.base.graphics`), not + through the package's star imports, which mypy cannot follow. +- New and changed code uses modern annotation syntax: `X | Y`, `X | None`, `list[X]`, + `dict[K, V]`, not `Union`, `Optional`, `List` or `Dict`. For array arguments use `ArrayLike` + (or `ArrayLike2` for a 2-element value) from `machinevisiontoolbox.mvtb_types`, and put the + shape in the docstring (`:type:`) only where it adds information. +- New and changed docstrings are reST with `:param:` first. An example is a `>>>` block under + `.. runblock:: pycon`, headed `.. rubric:: Examples` (always plural), and cross-references + are `.. seealso:: :meth:`other``, not the `:seealso:` field. A `.. versionadded::`, + `.. versionchanged::` or `.. deprecated::` names the release it ships in. Much existing code + still uses `Example:` and `:seealso:`; it is being migrated gradually, so follow the new + style in anything you touch rather than rewriting whole files. + +## If you are an AI assistant preparing a contribution + +- **Check for existing work before you write code.** Several agents often work on the same + open Issue at once. Search first: `gh pr list --state open --search "#"`, and check + the Issue's linked pull requests and assignee. If a PR exists or the Issue is assigned to + someone else, comment on it rather than opening a competing PR, and comment on the Issue to + claim it before you start. +- **Say so in the PR.** If an AI assistant wrote or substantially helped with the change, + state that, and which tool, in the PR description. You, the human, remain responsible and + should have read the diff. +- **Sign the commits.** An AI-assisted commit ends with a `Co-Authored-By:` trailer naming + the tool and model, and the PR description ends with the tool's attribution line. The + repository squash-merges, so the PR description is what survives; keep the disclosure there + too. +- Branch names are `type/short-description` (`fix/`, `feat/`, `docs/`, `chore/`, `refactor/`, + `test/`). The required checks are `All tests passed` and the PR title. +- Keep the PR to the one Issue or fix, and say what you ran and what you could not run.