From 226106267d83e2518fbd1e206fa557c90b301d99 Mon Sep 17 00:00:00 2001 From: Vinta Chen Date: Sun, 11 Oct 2026 09:47:37 +0800 Subject: [PATCH] docs: correct ranking, project count, and challenger wording DESIGN.md claimed ~650 projects (README has 506) and omitted the Downloads column the table sorts by; CONTRIBUTING.md said GitHub-linked projects rank higher when build.py sorts by PyPI downloads first and uses stars only for entries without downloads; ADR 0001 said challengers are "marked" while CONTRIBUTING.md says position is the only marker. Co-Authored-By: Claude --- CONTRIBUTING.md | 2 +- DESIGN.md | 4 ++-- docs/adr/0001-shortlist-not-catalog.md | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b5b50436..e9fe3a82 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -41,7 +41,7 @@ Looking for an exhaustive catalog instead? Follow the awesome-\* lists linked un ## Entry Format Reference -**Use GitHub repository URLs** whenever possible. Projects linked to a GitHub repo are ranked higher on [awesome-python.com](https://awesome-python.com/). +**Use GitHub repository URLs** whenever possible. [awesome-python.com](https://awesome-python.com/) shows stars and last-commit dates only for GitHub repos, and ranks entries without PyPI downloads by stars. ### Naming Convention diff --git a/DESIGN.md b/DESIGN.md index 56ea32bc..63b49348 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -6,7 +6,7 @@ description: Warm editorial Python index. Light cream canvas, brown-red interact # awesome-python.com DESIGN.md -awesome-python.com is a searchable, filterable index of ~650 curated Python projects. It is a reference tool, not a landing page and not a GitHub README mirror. +awesome-python.com is a searchable, filterable index of ~500 curated Python projects. It is a reference tool, not a landing page and not a GitHub README mirror. This file follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/overview/). The source of truth for token values lives in `website/static/style.css`. Color tokens here are written in OKLCH because the project mandates OKLCH over hex, which is a deliberate divergence from the spec's hex-only token requirement. @@ -19,7 +19,7 @@ Working Python developers (mid to senior) are the target reader. They write Pyth Jobs to be done: 1. Find a library for a specific need fast (search + tag filter). -2. Compare candidates at a glance (stars, last commit, tags, one-line description). +2. Compare candidates at a glance (downloads, stars, last commit, tags, one-line description). 3. Confirm a project is alive before clicking through. These users skim. They reward density and terse copy. They penalize marketing fluff. diff --git a/docs/adr/0001-shortlist-not-catalog.md b/docs/adr/0001-shortlist-not-catalog.md index 114cd2fa..3e22e128 100644 --- a/docs/adr/0001-shortlist-not-catalog.md +++ b/docs/adr/0001-shortlist-not-catalog.md @@ -8,7 +8,7 @@ By mid-2026 the list held 576 entries across 75 sections, with entry inflow up 2 ## The decision -The list's scope test is "serves Python developers", replacing the old "primarily written in Python (>50%)" requirement: implementation language and packaging are irrelevant when Python developers use the thing in their Python work (uv and ty are Rust; agent skill packs are markdown), while a pure-Python project nobody uses in Python work does not belong. Each Use Case (a subcategory, or a flat section) lists at most its Obvious Choices — up to 3, plus up to 2 marked Challengers, hard maximum 5 (numbers provisional, to be reviewed after the prune). Admission is by maintainer editorial judgment, informed primarily by PyPI download counts rather than GitHub stars, and stated as final; judgment overrides the signal's known failure modes (CI/dependency-inflated counts, model releases consumed as weights rather than pip installs, large-but-specific audiences misread as "niche"). Once a Use Case is at cap, the only way in is Displacement: the PR names the entry it replaces and argues the newcomer does that job better. Use Cases are defined by the list's existing structure; an entry PR can never create the subcategory it needs. Standard-library entries hold a slot only where the stdlib module is itself the obvious choice. The existing stock gets the same test retroactively: a staged, worst-first prune (per-section sweep commits), with removed entries deleted outright — git history is the archive. Resources sections (Newsletters, Podcasts, Websites) are out of scope for now. +The list's scope test is "serves Python developers", replacing the old "primarily written in Python (>50%)" requirement: implementation language and packaging are irrelevant when Python developers use the thing in their Python work (uv and ty are Rust; agent skill packs are markdown), while a pure-Python project nobody uses in Python work does not belong. Each Use Case (a subcategory, or a flat section) lists at most its Obvious Choices — up to 3, plus up to 2 Challengers, hard maximum 5 (numbers provisional, to be reviewed after the prune). Admission is by maintainer editorial judgment, informed primarily by PyPI download counts rather than GitHub stars, and stated as final; judgment overrides the signal's known failure modes (CI/dependency-inflated counts, model releases consumed as weights rather than pip installs, large-but-specific audiences misread as "niche"). Once a Use Case is at cap, the only way in is Displacement: the PR names the entry it replaces and argues the newcomer does that job better. Use Cases are defined by the list's existing structure; an entry PR can never create the subcategory it needs. Standard-library entries hold a slot only where the stdlib module is itself the obvious choice. The existing stock gets the same test retroactively: a staged, worst-first prune (per-section sweep commits), with removed entries deleted outright — git history is the archive. Resources sections (Newsletters, Podcasts, Websites) are out of scope for now. ## Considered options