Skip to content

13 - Picking a Project to Contribute To

What this session is

About 30 minutes plus your own browsing. You'll learn what makes a project a good first target, how to evaluate one in 10 minutes, and we'll list several real Python projects that consistently welcome new contributors.

Why the wrong project will burn you out

A first contribution to the wrong project goes like this:

  1. You pick something you use (Django, say).
  2. You spend three hours setting up the dev environment.
  3. You find a "good first issue" that hasn't been touched in six months.
  4. You spend two weeks understanding enough of the codebase to make a change.
  5. You submit a PR.
  6. Nobody reviews it for three weeks. A maintainer asks for changes you don't understand.
  7. You give up.

Every step in that story is normal. The fix isn't to be smarter; the fix is to pick a smaller, more responsive project first.

What "manageable" means

The criteria, in priority order:

  1. The project is small enough to comprehend. Under ~10k lines of Python is great for a first contribution. Under ~50k is doable. Above 100k, the orientation phase alone is a week.
  2. The maintainers are active. PRs get reviewed within a week, ideally a few days. Issues get responses.
  3. There are labeled "good first issue" or "help wanted" tickets. These are pre-screened to be approachable.
  4. There's a CONTRIBUTING.md. Tells you the project's conventions - coding style, tests they expect, the PR process.
  5. The tests run cleanly on a fresh clone. If pytest fails on git clone && pip install -e .[dev], that's a red flag about how careful the maintainers are.
  6. You actually understand or care about what the project does. Bonus, but real - motivation matters when you're stuck.

How to evaluate a project in 10 minutes

Open the GitHub page. Check, in order:

Signal What you're looking for
Stars More than ~100, less than ~50000. (Too few = abandoned, too many = crowded.)
Last commit date Within the last month. Older = inactive.
Open PRs Some, but not 200+. Look at how recent the most recent merged PR is.
PR merge time Pick 3 recently merged PRs. How many days from open to merge? Under 14 is healthy.
Open issues with good first issue label At least 5 is comfortable.
CONTRIBUTING.md Exists and is readable.
CI status Green ✓ on the main branch. Means tests pass.
Code of conduct Means maintainers think about how contributors are treated.

If a project fails on multiple of these, find another. There are thousands of Python projects on GitHub; you don't have to settle.

Several real candidates

These are Python projects that, as of 2026, have a track record of welcoming new contributors. Verify their current state with the 10-minute evaluation before you commit.

Tier 1: very small, very gentle

  • hynek/structlog - structured logging. ~5k LOC. Clean code; one of the friendliest maintainers in the ecosystem.
  • hynek/attrs - predecessor to dataclasses; still widely used. ~6k LOC.
  • peterbourgon/... - no, that's Go. Python equivalent: asottile/pre-commit-hooks - small hooks for the pre-commit framework. Tiny PRs welcome.
  • tartiflette/... - niche libraries, often <3k LOC and welcoming.

Tier 2: small to medium, well-organized

  • pallets/click - CLI framework. Well-documented, responsive.
  • encode/httpx - modern HTTP client. ~10k LOC.
  • tiangolo/typer - CLI library built on Click. Beginner-friendly issue labels.
  • samuelcolvin/pydantic - data validation. Larger (~30k LOC) but excellent maintainer ratio.
  • rich/rich (Will McGugan) - terminal formatting library. Wonderful README. Lots of issues at varying difficulties.

Tier 3: larger, more visible

After you've done a Tier 1 or 2 contribution.

  • pytest-dev/pytest - the test framework itself. Plenty of room for first contributions, especially in plugins.
  • pallets/flask - the web framework. Large but very welcoming.
  • scikit-learn/scikit-learn - ML library. Big, but documentation contributions are very accessible.
  • numpy/numpy - foundational. Documentation issues are the on-ramp.

Tier 4: massive - don't start here

  • django/django - yes, eventually. Not first.
  • python/cpython - Python itself. The process is slow even for senior contributors.
  • pytorch/pytorch - gigantic; mostly C++.

How to find issues

Once you've picked a project, visit its Issues tab.

Click "Labels." Filter by: - good first issue - help wanted - documentation (often the easiest first contribution) - easy or beginner (some projects use these instead)

Read 5-10 issues. Look for one where: - The description is clear ("X happens when Y, expected Z"). - The fix is contained ("update this string", "add a test for..."). - Nobody has claimed it (no comment like "I'm working on this"). - It hasn't been open for a year (older = harder than it looks).

Add a comment: "I'd like to take this. Can you confirm it's still wanted?" Wait for the maintainer's reply. Don't start work until they confirm.

What counts as a contribution

Don't underestimate small contributions. Real first contributions look like:

  • Fixing a typo in the README.
  • Adding a missing example in the documentation.
  • Adding a test case for an existing function.
  • Improving an error message to include more context.
  • Adding a type hint to an old function that lacks one.
  • Removing a deprecated dependency.
  • Fixing a small bug with a clear reproduction.

These are not "cheating." Every contribution is real. Maintainers prefer ten small clean PRs to one giant murky one. Your first PR's job is to get you through the workflow.

Exercise

Pick a project. Evaluate three; commit to one.

  1. Browse three projects from Tiers 1-2 above. For each, do the 10-minute evaluation. Write down the numbers in a notes file.

  2. Compare. Pick the one with the most responsive maintainers and at least 3 unclaimed first issues.

  3. Read its CONTRIBUTING.md end to end. Note unusual requirements (signed commits, specific PR templates, dev container).

  4. Clone it locally: 

    git clone https://github.com/<owner>/<repo>
cd <repo>

  5. Set up the dev environment per the CONTRIBUTING: 

    python -m venv .venv
source .venv/bin/activate
pip install -e .[dev]      # or whatever the project's instructions say
pytest                     # should pass
    If tests don't pass on fresh clone, consider a different project.

  6. Browse the open good first issue tickets. Pick two candidates. Don't claim either yet.

What you might wonder

"What if I don't see a good first issue label?" Some projects use other labels (help wanted, beginner-friendly, easy). Some don't label at all - look at recently closed PRs and see what kind of changes get merged. Documentation fixes are almost always welcome.

"What if my favorite project is too big?" Find a sub-project of it. The Pallets ecosystem (Flask) includes click, jinja2, werkzeug, itsdangerous - each smaller than Flask itself. Django has many smaller third-party packages (django-rest-framework's sub-packages, django-allauth, etc.) that are Tier 2.

"What if I find a bug but there's no issue for it?" File one first. Describe what you saw, what you expected, how to reproduce. Wait for acknowledgement. Then say "I'd like to send a fix."

"I'm worried about being judged for asking a basic question." (1) Most maintainers remember being new. (2) A polite, specific question is welcome. ("I tried X, expected Y, got Z" beats "doesn't work.") (3) A bad reception in the issue is itself useful information about the project. Try another.

Done

You can now: - Articulate what makes a project a "good first target." - Run a 10-minute evaluation on any GitHub project. - Recognize tiers and start at Tier 1 or 2. - Find issues appropriately sized for a first contribution. - Avoid the most common first-contribution traps.

You've chosen your target. The next page goes through the file structure of a real Python project so you know what every piece is for.

Next: Anatomy of a small Python OSS repo →

Comments