Saltar a contenido

13 - Picking a Project to Contribute To

What this session is

About 30 minutes plus browsing. You'll learn what makes a Java project a good first target, and we'll list several that consistently welcome new contributors.

Why the wrong project burns you out

A first contribution to the wrong project goes:

  1. You pick Spring (or Hibernate, or Kafka) because you've used it.
  2. Three hours setting up the dev environment.
  3. Find a "good first issue" untouched in six months.
  4. Two weeks understanding enough to make a change.
  5. Submit a PR.
  6. Three weeks of silence, then "could you rebase against trunk and address these 12 review comments?"
  7. You give up.

Fix: pick smaller, more responsive projects first.

What "manageable" means

In priority order:

  1. Small enough to comprehend. Under ~10k lines of Java is great. Under ~50k is doable. Above 100k, orientation alone is a week.
  2. Active maintainers. PRs reviewed in days, not weeks.
  3. good first issue / help wanted labels. Pre-screened for approachability.
  4. CONTRIBUTING.md. Spells out conventions.
  5. mvn test (or ./gradlew test) passes on fresh clone. If it doesn't, that's a red flag.
  6. You actually understand or care about what it does.

10-minute evaluation

Signal What you want
Stars 100-50000
Last commit Within a month
Open PRs Some, not 200+
Recent PR merge time Under 14 days
good first issue count At least 5
CONTRIBUTING.md exists and is readable yes
CI green on main yes
Code of conduct yes

If a project fails several, move on. Thousands of options.

Candidates

Verify state with the 10-minute eval before committing.

Tier 1 - very small

  • junit-team/junit5 - yes, the test framework itself. Big overall, but documentation and small-bug PRs are very accessible.
  • assertj/assertj-core - assertion library. Well-organized; lots of "add an assertion for X" issues.
  • google/truth - Google's assertion library. Active maintainers.
  • spring-projects-experimental/... - various small experiments under Spring's org.

Tier 2 - small to medium

  • apache/commons-lang - Apache utility library. Decades of polish, big community, many small issues.
  • apache/commons-io - sibling project for I/O utilities.
  • fastjson/fastjson2 - JSON library.
  • micrometer-metrics/micrometer - metrics library. Excellent maintainers; smaller PRs welcome.
  • resilience4j/resilience4j - circuit breaker library.
  • vavr-io/vavr - functional library for Java.

Tier 3 - bigger but well-documented

After Tier 1-2.

  • spring-projects/spring-boot - vast, but extremely well-labeled issues.
  • testcontainers/testcontainers-java - Docker-in-tests library.
  • elastic/elasticsearch - search engine. Java-heavy.
  • apache/kafka - message broker. Some good-first-issue work.

Tier 4 - massive, don't start here

  • openjdk/jdk - Java itself. The process is slow; CLA required; high bar.

Finding issues

On the project's GitHub, Issues → Labels. Filter by: - good first issue - help wanted - documentation

Read 5-10. Look for: - Clear description. - Contained fix. - Nobody claimed it. - Not open for a year.

Comment: "I'd like to take this. Can you confirm it's still wanted?" Wait for the maintainer.

What counts as a contribution

Small ones absolutely count: - Fix a typo in README or Javadoc. - Add a missing example. - Add a test case. - Improve an error message. - Add a @param Javadoc that's missing. - Fix a small bug with a clear reproduction.

Your first PR's job is to get you through the workflow.

Exercise

  1. Browse three projects from Tier 1-2. Do the 10-minute eval on each. Take notes.
  2. Pick the most responsive with at least 3 unclaimed issues.
  3. Read its CONTRIBUTING.md.
  4. Clone: 
    git clone https://github.com/<owner>/<repo>
cd <repo>
mvn test               # or ./gradlew test
    If tests fail on fresh clone, consider another project.
  5. Browse open good first issue tickets; pick two candidates. Don't claim yet.

What you might wonder

"What if my favorite project is too big?" Find a sub-project. Spring has dozens; Apache has dozens; Eclipse has dozens. Each is smaller than the umbrella.

"What if I find a bug but no issue?" File one first. Describe, wait for acknowledgement, then offer to fix.

Done

  • Articulate what makes a project a good first target.
  • Run a 10-minute evaluation.
  • Find appropriately-sized issues.
  • Avoid the most common traps.

Next: Anatomy of a Java OSS repo →

Comments