Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 49 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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 "#<issue>"`, 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.
Loading