diff --git a/.github/ISSUE_TEMPLATE/add-new-library-to-this-list.md b/.github/ISSUE_TEMPLATE/add-new-library-to-this-list.md deleted file mode 100644 index eba33ff6..00000000 --- a/.github/ISSUE_TEMPLATE/add-new-library-to-this-list.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -name: Add new library to this list -about: '' -title: '' -labels: '' -assignees: '' - ---- - -**Please open a Pull Request instead.** diff --git a/.github/ISSUE_TEMPLATE/add-xxx.md b/.github/ISSUE_TEMPLATE/add-xxx.md deleted file mode 100644 index 585f4919..00000000 --- a/.github/ISSUE_TEMPLATE/add-xxx.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -name: Add XXX -about: Add new item to the list -title: '' -labels: '' -assignees: '' - ---- - -**Please open a Pull Request instead.** diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index fdacb788..ab34f964 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,11 +1,20 @@ -## What is this Python project? +## Checklist -Describe features. +- [ ] One link per Pull Request +- [ ] PR title format: `Add project-name` +- [ ] Entry format: `* [project-name](url) - Description ending with period.` +- [ ] Description is concise (no mention of "Python") -## What's the difference between this Python project and similar ones? +## Why This Project Is Awesome -Enumerate comparisons. +Which criterion does it meet? (pick one) --- +- [ ] **Industry Standard** - The go-to tool for a specific use case +- [ ] **Rising Star** - 5,000+ stars in <2 years, significant adoption +- [ ] **Hidden Gem** - Exceptional quality, solves niche problems elegantly -Anyone who agrees with this pull request could submit an *Approve* review to it. +Explain: + +## How It Differs + +If similar entries exist, what makes this one unique? diff --git a/.github/workflows/claude-pr-review.yml b/.github/workflows/claude-pr-review.yml new file mode 100644 index 00000000..5e7702dc --- /dev/null +++ b/.github/workflows/claude-pr-review.yml @@ -0,0 +1,43 @@ +name: Claude PR Review + +on: + pull_request: + types: [opened, synchronize, ready_for_review, reopened, labeled] + paths: + - "README.md" + +jobs: + claude-pr-review: + if: | + github.event.label.name == 'claude-review' || + github.event.pull_request.author_association == 'FIRST_TIME_CONTRIBUTOR' || + github.event.pull_request.author_association == 'FIRST_TIMER' || + github.event.pull_request.author_association == 'NONE' + + runs-on: ubuntu-latest + + permissions: + contents: read # Cannot merge PR + pull-requests: write + issues: read + actions: read # Required for Claude to read CI results on PRs + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + with: + fetch-depth: 1 + + - name: Run Claude Code Review + id: claude-review + uses: anthropics/claude-code-action@v1 + with: + # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md + anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} + plugin_marketplaces: "https://github.com/anthropics/claude-code.git" + plugins: "code-review@claude-code-plugins" + prompt: | + Review this PR against the acceptance criteria in CONTRIBUTING.md. + Focus on: Industry Standard, Rising Star, or Hidden Gem criteria. + Check for automatic rejection reasons (abandoned, duplicates, spam). + /code-review:code-review ${{ github.repository }}/pull/${{ github.event.pull_request.number }} diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..81d13417 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,32 @@ +# CLAUDE.md + +## Repository Overview + +This is the awesome-python repository - a curated list of Python frameworks, libraries, software and resources. The repository serves as a comprehensive directory about Python ecosystem. + +## PR Review Guidelines + +**For all PR review tasks, refer to [CONTRIBUTING.md](CONTRIBUTING.md)** which contains: + +- Acceptance criteria (Industry Standard, Rising Star, Hidden Gem) +- Quality requirements +- Automatic rejection criteria +- Entry format reference +- PR description template + +## Architecture & Structure + +The repository follows a single-file architecture: + +- **README.md**: All content in hierarchical structure (categories, subcategories, entries) +- **CONTRIBUTING.md**: Submission guidelines and review criteria +- **sort.py**: Script to enforce alphabetical ordering + +Entry format: `* [project-name](url) - Concise description ending with period.` + +## Key Considerations + +- This is a curated list, not a code project +- Quality over quantity - only "awesome" projects +- Alphabetical ordering within categories is mandatory +- README.md is the source of truth for all content diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 943f93cb..a4a9c605 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,19 +2,126 @@ Your contributions are always welcome! -## Guidelines +## Quick Checklist -* Add one link per Pull Request. - * Make sure the PR title is in the format of `Add project-name`. - * Write down the reason why the library is awesome. -* Add the link: `* [project-name](http://example.com/) - A short description ends with a period.` - * Keep descriptions concise and **short**. -* Add a section if needed. - * Add the section description. - * Add the section title to Table of Contents. -* Search previous Pull Requests or Issues before making a new one, as yours may be a duplicate. -* Don't mention `Python` in the description as it's implied. -* Check your spelling and grammar. -* Remove any trailing whitespace. +Before submitting a PR, verify: -Just a gentle reminder: **Try not to submit your own project. Instead, wait for someone finds it useful and submits it for you.** +- [ ] One link per Pull Request +- [ ] PR title format: `Add project-name` +- [ ] Entry format: `* [project-name](url) - A short description ending with a period.` +- [ ] No mention of "Python" in description (it's implied) +- [ ] Description is concise (one sentence) +- [ ] No trailing whitespace +- [ ] Spelling and grammar checked + +## 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 (may have <500 stars) +- Solves niche problems elegantly +- Strong recommendation from experienced developers +- Must include compelling justification in PR description + +## Quality Requirements + +All submissions must satisfy **ALL** of these: + +1. **Python-first**: Primarily written in Python (>50% of codebase) +2. **Active**: Commits within the last 12 months +3. **Stable**: Production-ready, not alpha/beta/experimental +4. **Documented**: Clear README with examples and use cases +5. **Unique**: Adds distinct value, not "yet another X" + +## Automatic Rejection + +PRs will be **closed without review** if: + +- Project is archived or abandoned (no commits in 12+ months) +- Duplicate of existing entry without clear advantages +- No documentation or unclear use case +- Alpha/beta/experimental status +- Self-promotion (wait for someone else to find it useful and submit) +- Less than 500 GitHub stars AND not justified as a hidden gem + +## Entry Format Reference + +### Standard Entry + +```markdown +- [project-name](https://github.com/owner/repo) - Description ending with period. +``` + +### Standard Library Module + +```markdown +- [module](https://docs.python.org/3/library/module.html) - (Python standard library) Description. +``` + +### Fork of Another Project + +```markdown +- [new-name](https://github.com/owner/new-name) - Description ([original-name](original-url) fork). +``` + +### Entry with Related Awesome List + +```markdown +- [project](https://github.com/owner/project) - Description. + - [awesome-project](https://github.com/someone/awesome-project) +``` + +### Subcategory Format + +```markdown +- Subcategory Name + - [project](url) - Description. +``` + +## Adding a New Section + +If adding a new category: + +1. Add section description in italics: `*Libraries for doing X.*` +2. Add the section title to the Table of Contents +3. Keep sections in alphabetical order + +## PR Description Template + +Please include the following in your PR description: + +``` +## Why This Project Is Awesome + +[Explain which criterion it meets: Industry Standard / Rising Star / Hidden Gem] + +## How It Differs + +[If similar entries exist, explain what makes this one unique] +``` + +## Review Process + +PRs are reviewed by automated tools and maintainers: + +1. **Format Check**: Entry follows the correct format +2. **Duplicate Check**: Not already listed or previously rejected +3. **Activity Check**: Project shows recent activity +4. **Quality Check**: Meets acceptance criteria + +Search previous Pull Requests and Issues before submitting, as yours may be a duplicate.