From da340cb68c275a0a6e35b4370ced7f56e0d0945d Mon Sep 17 00:00:00 2001 From: Artur Shiriev Date: Sat, 17 Oct 2026 21:31:14 +0300 Subject: [PATCH] docs: plain-prose pass over agent and glossary docs --- AGENTS.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index df06b1ee..aa073255 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,30 +6,30 @@ contributor traffic: most merged PRs come from someone other than the maintainer Assume a human reviews your diff. `modern-di` is the newer framework from the same author, and this repo links to it, but -`that-depends` is actively maintained rather than deprecated. Do not rewrite anything +`that-depends` is still actively maintained. Do not rewrite anything here toward `modern-di`'s design, and do not carry conventions across in either -direction — the two repos diverge deliberately. +direction; the two repos diverge deliberately. ## Commands `just` (task runner) and `uv` (package manager). The [`justfile`](justfile) is the -source of truth — `just --list`, or read it. Two behaviours to know before running +source of truth: run `just --list`, or read it. Two behaviours to know before running anything: - `just lint` **rewrites files**. `just lint-ci` is the read-only twin and is what CI - runs. Use `lint-ci` when you want an answer rather than a mutation. + runs. Use `lint-ci` when you only want to check. - `just install` also installs the [`.pre-commit-config.yaml`](.pre-commit-config.yaml) hooks, so committing can change your working tree before the commit lands. `just unhook` removes them. -Type checking is **two** checkers — `mypy` in strict mode and `pyrefly` — and both must +Type checking is **two** checkers, `mypy` in strict mode and `pyrefly`, and both must be clean. There is no `ty` here, despite the org-level tooling note. ## Docs Docs are MkDocs Material, but **Read the Docs builds and hosts them** -([`.readthedocs.yaml`](.readthedocs.yaml) → `docs/requirements.txt` → `mkdocs.yml`) — -not the GitHub Pages workflow the rest of the org uses. Two consequences: +([`.readthedocs.yaml`](.readthedocs.yaml) → `docs/requirements.txt` → `mkdocs.yml`), +unlike the rest of the org, which uses the GitHub Pages workflow. Two consequences: - **Nothing builds the docs in CI.** A broken link or a bad snippet lands on `main` and only surfaces in the Read the Docs build afterwards. `just docs` serves the site @@ -62,7 +62,7 @@ single-file read will not tell you: `_ContainerMetaDict.__setitem__` reads it while the class body is still executing and raises `DefaultScopeNotDefinedError` otherwise. Statement order inside the class body is load-bearing. -- **Every public operation has a sync and an async twin** — `resolve`/`resolve_sync`, +- **Every public operation has a sync and an async twin**: `resolve`/`resolve_sync`, `override`/`override_sync`, `tear_down`/`tear_down_sync`, `context_async`/`context_sync`. Adding one half of a pair is an incomplete change. @@ -90,7 +90,7 @@ Every link in `README.md` must be absolute: `https://github.com/modern-python/` for a directory. Never a relative path: `README.md` is also the PyPI long description, and PyPI does not rewrite relative links, so a relative one 404s on the package page. -Unlike the rest of the org, **you are not the last reader of your diff** — a second +Unlike the rest of the org, **you are not the last reader of your diff**: a second party reviews and merges it. Write for them: what changed, why, and what you chose not to do. Keep one PR to one thing. @@ -100,13 +100,13 @@ work. This repo has no `docs/adr/` and no `CONTEXT.md`. A decision that outlives the PR goes in [`docs/dev/main-decisions.md`](docs/dev/main-decisions.md), which is a **user-facing -page** — write it for a reader of the docs site, not as an internal record. Issues live +page**: write it for a reader of the docs site, not as an internal record. Issues live on `modern-python/that-depends` itself (`gh issue create`), not on the org repo. ## Releases `pyproject.toml` carries `version = "0"` as a placeholder. The published version comes -from the git tag — publishing triggers on a GitHub release and `just publish` runs +from the git tag: publishing triggers on a GitHub release and `just publish` runs `uv version $GITHUB_REF_NAME`. **Never hand-edit `version`**; cut a release instead. ## Code style