From 59cc42e2c39165ae44b925002f552e18083abe6a Mon Sep 17 00:00:00 2001 From: Vinta Chen Date: Sun, 16 Aug 2026 00:38:48 +0800 Subject: [PATCH] docs: sync AGENTS.md with the shortlist reform rules AGENTS.md still carried pre-reform Key Rules (mandatory alphabetical ordering, "quality over quantity" lanes-era language, no prune-sweep commit exception, no live-verification rule). Bring it in line with CLAUDE.md and CONTRIBUTING.md: downloads-descending tier ordering, 3+2 cap, sweep-commit exception, verification rule. Also record the UV_PYTHON=3.13 workaround for Python-3.14-only machines in both files' Makefile notes, and complete CLAUDE.md's Makefile target list. Co-Authored-By: Claude --- AGENTS.md | 13 +++++++------ CLAUDE.md | 2 +- 2 files changed, 8 insertions(+), 7 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 29c863bc..646889dc 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,11 +6,11 @@ An opinionated list of Python frameworks, libraries, tools, and resources. Publi ## Entry Guidelines -**Refer to [CONTRIBUTING.md](CONTRIBUTING.md)** for acceptance criteria, quality requirements, rejection rules, and entry format. Apply these rules whenever adding or removing an entry, whether reviewing a PR or committing directly. +**Refer to [CONTRIBUTING.md](CONTRIBUTING.md)** for admission rules, quality requirements, rejection rules, and entry format. Apply these rules whenever adding or removing an entry, whether reviewing a PR or committing directly. ## Structure -- **README.md**: Source of truth for catalog entries and README sponsor placements. Hierarchical categories with alphabetically ordered entries. +- **README.md**: Source of truth for catalog entries and README sponsor placements. Hierarchical categories; entries ordered per the Key Rules below. - **CONTRIBUTING.md**: Submission guidelines and review criteria. - **SPONSORSHIP.md**: Sponsor tiers, placement rules, and the editorial-independence policy. `website/templates/sponsorship.html` separately defines which sponsorship content appears on the published website page. - **website/**: Static site generator that builds awesome-python.com from README.md. @@ -19,13 +19,14 @@ An opinionated list of Python frameworks, libraries, tools, and resources. Publi - `readme_parser.py`: Markdown-to-structured-data parser. - `templates/`, `static/`: Jinja2 templates and CSS/JS assets. - `tests/`: Pytest tests for the build pipeline. -- **Makefile**: `make install`, `make build`, `make preview`, `make test`, `make lint`, `make format`, `make typecheck`, `make fetch_github_stars`. +- **Makefile**: `make install`, `make build`, `make preview`, `make test`, `make lint`, `make format`, `make typecheck`, `make fetch_github_stars`. On machines with only Python 3.14, prefix uv-based targets with `UV_PYTHON=3.13` (watchdog 6.0.0 ships no 3.14 wheel and the project sets `no-build`). - **pyproject.toml**: Uses `uv` for dependency management. Python >=3.13. ## Key Rules -- Alphabetical ordering within categories is mandatory. -- Quality over quantity. Only "awesome" projects. +- Ordering within a use case: obvious choices first, then challengers, each tier by PyPI downloads/month descending; no-signal entries last in tier, alphabetically. See CONTRIBUTING.md. +- A shortlist, not a catalog: per use case, up to 3 obvious choices plus up to 2 challengers, hard maximum 5. - One project per PR. -- One entry per commit when adding or deleting entries. Format, wording, or categorization changes across multiple entries may be bundled in a single commit. +- One entry per commit when adding or deleting entries. Exception: a prune sweep is one commit per section, its body listing each removal with its reason. Format, wording, or categorization changes across multiple entries may be bundled in a single commit. +- Every keep/drop reason must be verified against current online data at decision time — download counts, repo activity and archived status, PyPI metadata, project docs. Training-data recollections alone are not evidence; verify before stating, and label anything unverifiable as a judgment call. - README.md is the source of truth for catalog entries and README sponsor placements; treat `SPONSORSHIP.md` and `website/templates/sponsorship.html` as separate sponsorship content surfaces. diff --git a/CLAUDE.md b/CLAUDE.md index da1c684b..52b9391c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -19,7 +19,7 @@ An opinionated list of Python frameworks, libraries, tools, and resources. Publi - `readme_parser.py`: Markdown-to-structured-data parser. - `templates/`, `static/`: Jinja2 templates and CSS/JS assets. - `tests/`: Pytest tests for the build pipeline. -- **Makefile**: `make install`, `make build`, `make preview`, `make test`, `make fetch_github_stars`. +- **Makefile**: `make install`, `make build`, `make preview`, `make test`, `make lint`, `make format`, `make typecheck`, `make fetch_github_stars`. On machines with only Python 3.14, prefix uv-based targets with `UV_PYTHON=3.13` (watchdog 6.0.0 ships no 3.14 wheel and the project sets `no-build`). - **pyproject.toml**: Uses `uv` for dependency management. Python >=3.13. ## Key Rules