From ac46dcad869dfebbc9447c20339d899d1c792bec Mon Sep 17 00:00:00 2001 From: Peter Corke Date: Fri, 20 Nov 2026 07:42:26 +1000 Subject: [PATCH 1/4] docs: add AI-assistant contribution rules to AGENTS.md Co-Authored-By: Claude Sonnet 5.5 --- AGENTS.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 3beccb67..4f883b91 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -28,3 +28,21 @@ 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. + +## 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. From a0dff3a725811032407962ca7a319964989c3f7b Mon Sep 17 00:00:00 2001 From: Peter Corke Date: Fri, 20 Nov 2026 07:43:14 +1000 Subject: [PATCH 2/4] docs: add mypy guidance to AGENTS.md Co-Authored-By: Claude Sonnet 5.5 --- AGENTS.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 4f883b91..c76399fa 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -28,6 +28,12 @@ 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. ## If you are an AI assistant preparing a contribution From 202e65bba607b36ceedd38940e25e37c2d61e4cb Mon Sep 17 00:00:00 2001 From: Peter Corke Date: Fri, 20 Nov 2026 07:44:49 +1000 Subject: [PATCH 3/4] docs: add type hint and docstring conventions to AGENTS.md Co-Authored-By: Claude Sonnet 5.5 --- AGENTS.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index c76399fa..a02fb58d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -34,6 +34,16 @@ Part of the RVC ecosystem. **Read [rvc-ecosystem/AGENTS.md](https://github.com/p 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 From b2d22d8a2ea3c58393b518645102c211f645989c Mon Sep 17 00:00:00 2001 From: Peter Corke Date: Fri, 20 Nov 2026 07:46:31 +1000 Subject: [PATCH 4/4] docs: add project goals to AGENTS.md Co-Authored-By: Claude Sonnet 5.5 --- AGENTS.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index a02fb58d..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.