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 Go 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 (Kubernetes, 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. Then 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 Go 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. go test ./... from a fresh clone should pass. If it doesn't on a fresh checkout, 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 Filter the issue list. At least 5 is comfortable.
CONTRIBUTING.md Exists and is readable.
CI status A 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 Go projects on GitHub; you do not have to settle.

Several real candidates

These are Go 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

  • peterbourgon/ff - flag and config library. ~2-3k LOC. Tiny scope.
  • fatih/color - terminal color library. ~1k LOC. One file does most of the work.
  • spf13/pflag - POSIX-style flag library. ~5k LOC. Used by cobra, kubectl, and many others.
  • stretchr/testify - testing assertions and mocks. ~10k LOC across many small subpackages. Pick one subpackage to focus on.

Tier 2: small to medium, well-organized

  • urfave/cli - CLI application framework. ~10k LOC. Excellent docs, clear architecture, responsive maintainers.
  • go-chi/chi - HTTP router. ~5k LOC. Idiomatic Go HTTP code; great to read.
  • pkg/errors - error wrapping (predecessor to standard library %w). Tiny. Still receives small contributions.
  • magefile/mage - Make-replacement in Go. ~5k LOC.
  • spf13/viper - config library. ~10k LOC. Heavily used, but has plenty of low-hanging issues.

Tier 3: larger, more visible

These are good targets after you've completed a contribution to a Tier 1 or 2 project.

  • hashicorp/terraform-provider-... - many small providers each manage one cloud service. Pick one whose service you've used.
  • prometheus/... - multiple repos in the Prometheus monitoring ecosystem. Some are small enough to be Tier 2.
  • grafana/grafana or grafana/loki - large, but with very labeled first issues.

Tier 4: massive - don't start here

  • kubernetes/kubernetes - the world. Wait until you have several other contributions.
  • golang/go - Go itself. Takes months to land a first patch even for senior engineers. There are easier wins.

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 - a docs improvement is much less risky than a code change)

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 - claiming an issue without confirmation can step on someone else's toes.

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.
  • Removing a deprecated dependency.
  • Fixing a small bug with a clear reproduction.

These are not "cheating." Every contribution is real, and every maintainer will tell you they prefer ten small clean PRs to one giant murky one. Your first PR's job is to get you through the workflow, not to rewrite the project.

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 (stars, last commit, recent PR merge time, count of good first issues) in a notes file.

  2. Compare. Pick the one that scores best on responsiveness and has at least 3 unclaimed first issues.

  3. Read its CONTRIBUTING.md end to end. Note any unusual requirements (e.g., signed commits, specific commit message format, dev container).

  4. Clone it locally: 

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

  5. Run its tests: 

    go test ./...
    Confirm they pass. If they don't on a fresh clone, that's a red flag - you may want to pick a different project.

  6. Browse the open good first issue tickets. Pick two candidates for your eventual contribution. Don't claim either yet. Read each carefully and decide which feels more contained.

You're not contributing anything yet. You're choosing the playing field. The choice matters more than people think.

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 - in that case, look at recently closed PRs and see what kind of changes get merged. Documentation fixes are almost always welcome, even unlabeled.

"What if my favorite project is too big?" Find a sub-project of it. The Kubernetes ecosystem includes dozens of smaller repos under kubernetes-sigs/ - many are Tier 2 in size. Same for prometheus/, grafana/, cncf/.

"What if I find a bug but there's no issue for it?" File one before submitting a PR. Describe what you saw, what you expected, how to reproduce. Wait for a maintainer to acknowledge it; sometimes the bug is intentional or already being worked on. Then say "I'd like to send a fix."

"I'm worried about being judged for asking a basic question on the issue." Three notes. (1) Most maintainers remember being new. (2) A polite, specific question is welcome. ("I tried X, expected Y, got Z" is much better than "doesn't work".) (3) A bad reception in the issue is itself useful information about the project. If you sense hostility, try a different project.

Done

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

You've chosen your target. The next page is the practical work of getting your local environment set up to work on it.

Next: Anatomy of a small OSS repo → 14-anatomy-of-a-small-oss-repo.md

Comments