mirror of
https://github.com/TheAlgorithms/Python.git
synced 2026-09-28 21:45:27 +08:00
priya-sundaram-dev
72d2eecd7f
* docs: add AGENTS.md with contribution rules for AI agents Adds a model-neutral AGENTS.md at the repo root summarizing the conventions that most often trip up automated contributors, most importantly that algorithms-keeper closes any PR without a checked box in the 'Describe your change' section. Complements CONTRIBUTING.md. * docs: use uvx/uv commands in AGENTS.md (this repo uses uv, not requirements.txt)
63 lines
2.8 KiB
Markdown
63 lines
2.8 KiB
Markdown
# AGENTS.md
|
|
|
|
Guidance for AI coding agents (and their humans) contributing to
|
|
**TheAlgorithms/Python**. This complements — and never overrides —
|
|
[`CONTRIBUTING.md`](CONTRIBUTING.md). Read that first.
|
|
|
|
This repository is educational: implementations should be clear and correct
|
|
rather than maximally optimized. Every change goes through CI and the
|
|
`algorithms-keeper` bot, both of which reject non-conforming PRs automatically.
|
|
|
|
## Before opening a pull request
|
|
|
|
- **Check at least one box in the PR description.** The `algorithms-keeper`
|
|
bot **closes any PR whose "Describe your change" section has no checked
|
|
box** (`* [x]`). Fill in the template that ships in
|
|
`.github/pull_request_template.md` and tick every item that applies before
|
|
you submit — this is the single most common reason automated PRs get closed.
|
|
- **One algorithm file per PR.** Split unrelated changes into separate PRs to
|
|
keep review focused.
|
|
- **Don't change code and its doctests in the same PR.** If you're only
|
|
updating tests, say so and touch nothing else.
|
|
|
|
## Code conventions (enforced by CI)
|
|
|
|
- **Formatting & linting:** `ruff` (`uvx ruff check .` and `uvx ruff format .`).
|
|
Run `uvx pre-commit run --all-files` locally to catch everything CI will.
|
|
- **Type hints:** annotate every function parameter and return value with
|
|
[type hints](https://docs.python.org/3/library/typing.html).
|
|
- **Doctests:** every function needs at least one
|
|
[doctest](https://docs.python.org/3/library/doctest.html) that passes under
|
|
`python -m doctest -v your_file.py` (and `pytest`).
|
|
- **Naming:** filenames are all-lowercase with underscores (no spaces or
|
|
dashes); functions and variables follow standard Python naming.
|
|
- **Placement:** new files go inside an existing directory.
|
|
- **References:** new algorithms include a URL to Wikipedia or a comparable
|
|
explanation.
|
|
|
|
## Running the suite locally
|
|
|
|
This project is managed with [`uv`](https://docs.astral.sh/uv/) — there is no
|
|
`requirements.txt`. Dependencies live in `pyproject.toml`/`uv.lock`, and `uvx`
|
|
runs a tool in a throwaway environment without polluting yours:
|
|
|
|
```bash
|
|
uvx pre-commit run --all-files # ruff, formatting, hooks
|
|
uvx pytest your_module/your_file.py --doctest-modules
|
|
```
|
|
|
|
(`uv run pytest ...` works too if you'd rather use the project's locked
|
|
environment.)
|
|
|
|
Some directories are intentionally skipped in CI (`--ignore` entries in
|
|
`.github/workflows/build.yml`), usually because a heavy dependency lacks a
|
|
wheel for the CPython version the repo currently targets. Check that list
|
|
before assuming a file is untested.
|
|
|
|
## Good agent behavior
|
|
|
|
- Keep diffs minimal and scoped to the stated change.
|
|
- Preserve existing style and structure; prefer clarity over cleverness.
|
|
- Never fabricate doctest output — run it and paste the real result.
|
|
- If CI is red, read the log and fix the cause rather than re-running blindly.
|