Skip to content

Commit a09f148

Browse files
authored
docs(agents): point at the standard instead of restating it (#100)
#96: the metadata rules live in section 11 of the standard, the toolchain in section 1, and the exemptions table records that that-depends keeps its own tooling; two copies drift. What stays is specific to this repo: the profile's badge facts, the brand surfaces, the CI stale-merge-ref gotcha, and the agent-skill pointers. Two agent-facing gotchas that only AGENTS.md carried move into section 11: never the keyword "dependency injector", and validate classifier strings against pypi.org.
1 parent 0a92f98 commit a09f148

2 files changed

Lines changed: 9 additions & 40 deletions

File tree

‎AGENTS.md‎

Lines changed: 6 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -9,40 +9,14 @@ before naming a mark, a colourway, or a surface.
99
(not "LiteStar"), `FastStream`, `FastAPI`, `Typer`, `SQLAlchemy`, `PostgreSQL`.
1010
- Per-project docs sites live at `<name>.modern-python.org` (only some repos have one).
1111

12-
## Repository metadata (three surfaces kept consistent)
12+
## Repository metadata
1313

14-
Every repo's summary appears in up to three places — keep them saying the same thing:
15-
the **GitHub description**, the pyproject **`description`**, and the repo's blurb in
16-
`profile/README.md`. Write one canonical one-liner per repo: purpose-first,
17-
≤ ~120 chars, **no trailing period** (GitHub convention).
14+
A repo's description, topics, keywords, classifiers and `[project.urls]` follow
15+
[section 11 of the standard](https://modern-python.org/standard/#11-metadata).
1816

19-
### GitHub topics
20-
- Lowercase letters/numbers/hyphens only, ≤50 chars each, ≤12 per repo.
21-
- Draw from the shared org vocabulary so `/topics/*` pages cluster: `python`,
22-
`dependency-injection`, `di`, `ioc-container`, `modern-di`, `fastapi`, `litestar`,
23-
`faststream`, `sqlalchemy`, `postgresql`, `asyncio`, `docker`, `cli`, `messaging`.
24-
- `modern-di-*` integrations share a base set
25-
(`python, dependency-injection, di, ioc-container, modern-di`) plus their framework.
26-
- Also set the repo **website field** to its docs site, or `modern-python.org` if none.
27-
28-
### pyproject `[project]`
29-
- **`keywords`** mirror the GitHub topics (lowercase/hyphenated). Never use
30-
`"dependency injector"` — that is another package's name (`dependency-injector`).
31-
- **`classifiers`**: include `Development Status :: <level>`,
32-
`Intended Audience :: Developers`, the relevant `Programming Language :: Python ::`
33-
versions, `Typing :: Typed`, and a `Topic ::` where apt. Validate every string
34-
against <https://pypi.org/classifiers/> before committing.
35-
- **Do NOT add a `License :: OSI Approved :: ...` classifier.** All repos are MIT and
36-
declare the SPDX `license = "MIT"` key; PEP 639 deprecates pairing that with a
37-
License classifier, and `uv_build` warns on it.
38-
- **`[project.urls]`** uses PyPI well-known labels (capitalized):
39-
`Homepage`, `Documentation` (only if a docs site exists), `Repository`,
40-
`Issues` (`…/issues`), `Changelog` (`…/releases`).
41-
42-
The PyPI distribution name equals the repo name, for every package. The org
43-
profile's `coverage 100%` badge is static and deliberately unlinked — the claim holds
44-
because every repo's CI enforces a 100%-coverage guard, and there is no org-level
45-
coverage URL to point at.
17+
The org profile's `coverage 100%` badge is static and deliberately unlinked: there is no
18+
org-level coverage URL to point at, and the gate in section 5 of the standard is what
19+
makes the claim true.
4620

4721
A repo may be listed on the org profile **before** its package reaches PyPI. Its
4822
Downloads badge 404s until pepy indexes it; the Stars badge and repo link resolve
@@ -56,12 +30,6 @@ A docs site's `docs/index.md` replaces its `# <Title>` heading with a `.mp-hero`
5630
holding both lockup variants. Add no `title:` front matter there: Material titles the
5731
home page from `site_name`, so `title:` renders as `<repo> - <repo>`.
5832

59-
## Tooling
60-
61-
Projects use **uv** (packaging), **ruff** (lint/format), **ty** (type check), and
62-
the build backend is **uv_build**. `that-depends` additionally runs `mypy` and
63-
`pyrefly` in its `lint-ci` recipe. Lint/test live behind a `justfile` in most repos.
64-
6533
## CI gotcha
6634

6735
GitHub occasionally type-checks a **stale `refs/pull/<n>/merge`** after a push, so a

‎docs/standard.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -198,12 +198,13 @@ purpose-first, about 120 characters at most, no trailing period.
198198
`dependency-injection`, `di`, `ioc-container`, `modern-di`, `fastapi`, `litestar`, `faststream`,
199199
`sqlalchemy`, `postgresql`, `asyncio`, `docker`, `cli`, `messaging`). The website field is the
200200
docs site, or `modern-python.org`.
201-
- **`keywords`** mirror the topics.
201+
- **`keywords`** mirror the topics. Never `dependency injector`: that is another package's name
202+
(`dependency-injector`).
202203
- **`classifiers`**: `Development Status`, `Intended Audience :: Developers`, one
203204
`Programming Language :: Python :: 3.X` per tested minor,
204205
`Programming Language :: Python :: Free Threading :: 2 - Beta` when the matrix's free-threaded
205206
entry is green (section 6; a repo exempt from that entry omits it), `Typing :: Typed`, a `Topic`
206-
where apt.
207+
where apt. Validate each string against <https://pypi.org/classifiers/>.
207208
**No `License ::` classifier**: the SPDX `license = "MIT"` key is the declaration, and PEP 639
208209
deprecates pairing it with a classifier.
209210
- **`[project.urls]`** uses the PyPI labels `Homepage`, `Documentation` (only if a docs site

0 commit comments

Comments
 (0)