Skip to content

Appendix C - Contributing to OpenJDK

The deliverable of master-level Java is the credible claim that you can debug, patch, and (modestly) extend the JDK itself. This appendix is the entrance guide: how the project is structured, where to start, and how to land your first change.

It is not a substitute for the official OpenJDK developer guide (openjdk.org/guide/) - it is the on-ramp to it.

C.1 The Project Topology

  • OpenJDK is the reference implementation. Owned by Oracle, governed by the OpenJDK community, vendored by Adoptium, Amazon Corretto, Azul Zulu, Microsoft, Red Hat, BellSoft, Eclipse Temurin, etc. The same source - different builds and support contracts.
  • The canonical repo: github.com/openjdk/jdk (the mainline) plus update repos (jdk21u, jdk25u) for LTS maintenance.
  • Smaller related repos: openjdk/jdk-sandbox (experimental), per-project repos (Loom historically lived in openjdk/loom, etc.; many have been integrated upstream now).

The directory layout you care about:

src/
  java.base/share/classes/      # Core class library (java.lang.*, java.util.*, java.io.*, ...)
  java.base/share/native/       # Native bits supporting java.base
  hotspot/share/runtime/        # The JVM runtime - threads, frames, monitors
  hotspot/share/gc/             # Garbage collectors (g1/, z/, parallel/, serial/, shenandoah/)
  hotspot/share/opto/           # C2 compiler
  hotspot/share/c1/             # C1 compiler
  hotspot/share/classfile/      # Class loading & verifier
  jdk.compiler/share/classes/   # javac
  ...
test/
  jdk/                          # JTReg tests for the JDK class library
  hotspot/jtreg/                # JTReg tests for HotSpot
  micro/                        # JMH benchmarks in-tree

If you don't know which directory your change belongs in, you don't yet understand the change. Read until you do.

C.2 Process: From Bug to Patch

  1. JBS (bugs.openjdk.org) is the issue tracker. Search there before reporting. Most "bugs" turn out to be JEP-tracked design choices.
  2. Mailing lists. Every component has one. hotspot-dev, core-libs-dev, loom-dev, panama-dev, compiler-dev, etc. Subscribe to the one matching your interest and lurk for at least a month before posting. Read tone before contributing tone.
  3. Author the change. Build the JDK yourself (bash configure && make images). Run the relevant test groups (make test TEST=tier1).
  4. Submit via Skara. OpenJDK uses a GitHub-bot pipeline called Skara. You open a PR against openjdk/jdk. The bot enforces:
  5. Signed OCA (Oracle Contributor Agreement) - required for non-trivial changes. Trivial fixes (typos, comments) often go through without OCA, but check the bot's response.
  6. Reviewer requirements (most areas require two Reviewers; "Reviewer" is a formal role).
  7. JBS issue linkage.
  8. Clean commit history (one logical change, well-described).
  9. Reviews are technical and pointed. Don't take it personally. Address every comment in the PR or in the mailing-list discussion.
  10. Integration. Once approved, you (or a Reviewer with integration rights) issue /integrate. The bot lands it in the right branch.

C.3 The First-Patch Playbook

Pick from this in roughly ascending difficulty:

Tier 0 - Documentation and Javadoc

Find a Javadoc error, clarification opportunity, or broken {@link}. File JBS, submit PR. Surfaces you to the workflow without engineering risk.

Tier 1 - Test improvements

The test base is large and uneven. Look for @ignore or TODO-flagged tests. Or: add a regression test for a recently fixed bug that didn't get one (common). Reviewers love these.

Tier 2 - Small java.base improvements

The classic on-ramp: a missing @Override annotation; a for loop that could be enhanced; a string concat in a hot path; a StringBuilder reuse. Look at recent commits to java.base/share/classes for the style of acceptable small changes.

Tier 3 - HotSpot bugfixes from JBS

Filter JBS by priority = P4 and affects-version = openjdk25 (or current). Read the bug. If you can reproduce it locally and the fix is < 50 lines, it's a first-patch candidate. Read the related code first; HotSpot has rich conventions (NULL checks, ResourceMark, HandleMark, mutex order) you must respect.

Tier 4 - Garbage collector internals

Don't start here. After a year on tier-3 patches, with a clear interest in GC research, follow hotspot-gc-dev.

Tier 5 - Compiler (C2 / Graal) work

Don't start here either. C2 has a steep on-ramp; expect 6+ months of reading before a credible patch.

C.4 Building OpenJDK Locally

git clone https://github.com/openjdk/jdk
cd jdk

# Linux deps (Debian/Ubuntu): autoconf, build-essential, libx11-dev, libxext-dev,
# libxrender-dev, libxrandr-dev, libxtst-dev, libxt-dev, libcups2-dev, libfontconfig1-dev,
# libasound2-dev, libfreetype6-dev, zip, unzip.

bash configure --with-boot-jdk=$JAVA_HOME --enable-ccache
make images

# Resulting JDK:
./build/linux-x86_64-server-release/images/jdk/bin/java --version

For day-to-day hacking: make hotspot (just the VM, ~3 min incremental) is faster than make images. Use --with-debug-level=fastdebug for development - assertions and verifier on, optimization on, build time tolerable.

Run tests:

make test TEST="tier1"
make test TEST="jtreg:test/hotspot/jtreg/runtime/InvocationTests"
make test TEST="micro:org.openjdk.bench.java.util.HashMapBench"

JTReg is the JDK's test harness; you'll learn it by reading existing tests in test/.

C.5 Reading the Code

Three habits that compound:

  1. Follow one bug from JBS to integration. Pick a recent fix. Read the JBS entry, the mailing-list discussion, the PR, the commits. Do this monthly until the patterns of "what gets accepted" are obvious.
  2. Annotate as you read. HotSpot in particular is unforgivingly terse. Keep a private notebook of "what I learned from mutex.cpp today." Re-read your own notes weekly.
  3. Compile and instrument. When you don't understand a code path, add tty->print_cr("hello from %s", __FUNCTION__); (HotSpot) or System.err.println (java.base, in your local build), rebuild, run a test, observe. This is the single fastest way to learn.

C.6 The Etiquette

  • Lurk before posting. The mailing lists have decades of context. Posting "I want to contribute, what should I do?" generates eye-rolls.
  • Don't bikeshed. Disagreements happen - make them on technical merits, drop them after the second exchange.
  • OCA before non-trivial PR. Sign the Oracle Contributor Agreement at oca.opensource.oracle.com before you have a patch ready, so it's done.
  • Credit and copyright headers. The build cares; don't break the conventions.
  • Reviewers are paid in patience. Yours, and theirs. Make changes easy to review: one logical change per PR, clean diff, descriptive title with the JBS ID (8312345: Make HashMap.resize() handle X correctly).

C.7 Beyond the JDK

Some adjacent JVM-ecosystem projects that compound your OpenJDK fluency:

  • GraalVM (oracle.com/graalvm, source on GitHub) - Truffle, Native Image, the Graal compiler. Different governance, OCA-like CLA.
  • Eclipse OpenJ9 / OMR - IBM's JVM. Different runtime, different GC family, useful contrast.
  • Adoptium / Eclipse Temurin - build/QA work for the OpenJDK; high-value, lower-engineering on-ramp.
  • Major OSS JVM frameworks - Netty, Spring, Quarkus, Apache Kafka, Cassandra. Patching any of these at depth trains the same muscles as patching the JDK.

The path from "I wrote a Spring app" to "I committed to java.base" is real and walkable. Most who walk it spend 6–18 months on the on-ramp before their first integration. Plan accordingly, and start with a Tier-0 contribution this month.

Comments