mirror of https://github.com/TheAlgorithms/Python.git synced 2026-09-28 21:45:27 +08:00

Files

T

priya-sundaram-dev 72d2eecd7f docs: add AGENTS.md with contribution rules for AI agents (#15121 )

* 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)

2026-08-30 12:59:57 +02:00

2.8 KiB

Raw Permalink Blame History

AGENTS.md

Guidance for AI coding agents (and their humans) contributing to TheAlgorithms/Python. This complements — and never overrides — 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.
Doctests: every function needs at least one doctest 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 — there is no requirements.txt. Dependencies live in pyproject.toml/uv.lock, and uvx runs a tool in a throwaway environment without polluting yours:

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.