mirror of https://github.com/vinta/awesome-python.git synced 2026-03-24 01:24:43 +08:00

Files

Vinta Chen 6204196083 docs: add naming convention rule to CONTRIBUTING.md

Prefer PyPI package name as display name so developers can copy it
directly to pip install. Fall back to GitHub repo name if not on PyPI.
Also update examples to use lowercase PyPI names.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

2026-03-19 01:24:26 +08:00

3.4 KiB

Raw Blame History

Contributing

Quality Requirements

All submissions must satisfy ALL of these:

Python-first: Primarily written in Python (>50% of codebase)
Active: Commits within the last 12 months
Stable: Production-ready, not alpha/beta/experimental
Documented: Clear README with examples and use cases
Unique: Adds distinct value, not "yet another X"
Established: Repository at least 1 month old

Acceptance Criteria

Your submission must meet ONE of the following criteria:

1. Industry Standard

The go-to tool that almost everyone uses for a specific use case
Examples: requests, flask, pandas, numpy
Limit: 1-3 tools per category

2. Rising Star

Rapid growth: 5,000+ GitHub stars in less than 2 years
Significant community buzz and adoption
Solving problems in new or better ways
Examples: fastapi, ruff, uv

3. Hidden Gem

Exceptional quality despite fewer stars (100-500 stars preferred; < 100 requires strong justification)
Solves niche problems elegantly
Strong recommendation from experienced developers
Must demonstrate real-world usage (not a project published last week)
Repository must be at least 6 months old with consistent activity
Must include compelling justification in PR description

Entry Format Reference

Use GitHub repository URLs whenever possible. Projects linked to a GitHub repo are ranked higher on awesome-python.com.

Naming Convention

Use the PyPI package name as the display name so developers can copy it directly to pip install. Check the canonical name at https://pypi.org/pypi/{package}/json. If the project is not on PyPI, use the GitHub repository name instead.

Standard Entry

- [pypi-name](https://github.com/owner/repo) - Description ending with period.

Standard Library Module

- [module](https://docs.python.org/3/library/module.html) - (Python standard library) Description.

Fork of Another Project

- [new-name](https://github.com/owner/new-name) - Description ([original-name](original-url) fork).

- [project](https://github.com/owner/project) - Description.
  - [awesome-project](https://github.com/someone/awesome-project)

Subcategory Format

- Subcategory Name
  - [project](url) - Description.

Adding a New Section

Add section description in italics: *Libraries for doing X.*
Add the section title to the Table of Contents
Keep sections in alphabetical order

Review Process

PRs are reviewed by automated tools and maintainers:

Format Check: Entry follows the correct format
Category Check: Placed in the appropriate category/subcategory
Duplicate Check: Not already listed or previously rejected
Activity Check: Project shows recent activity
Quality Check: Meets acceptance criteria

Search previous Pull Requests and Issues before submitting, as yours may be a duplicate.

Automatic Rejection

PRs will be closed if:

Adding multiple projects in one PR
Duplicate of existing entry or recently-closed PR
Empty or placeholder PR descriptions
Placed under an inappropriate category
Project is archived or abandoned (no commits in 12+ months)
No documentation or unclear use case
Less than 100 GitHub stars without Hidden Gem justification
Repository less than 3 months old

3.4 KiB Raw Blame History