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