Introduction

Welcome to the OpenJDK Developers’ Guide!

The OpenJDK Community is the place to collaborate on open-source implementations of the Java Platform, Standard Edition, and related projects. It was created in November 2006, when initial portions of the JDK source code were published under the GPLv2 license.

In order to work together efficiently, clear directions are sometimes needed to avoid misconceptions and to align developers’ views of terminology and process. The OpenJDK Community is a fairly pragmatic place. “Do the right thing” is most often the right course of action. Still, if people do things in the same right way then everyone’s work becomes more transparent and easier for others to follow. For this reason most parts of the development process have standard flows that are the recommended ways to do things.

The goal of this guide is to answer questions that developers of the JDK might have around development process, tooling, standards, and so forth. The formal rules and processes are described in other documents, such as JEP 1 for the JDK Enhancement-Proposal & Roadmap Process, and JEP 3 for the JDK Release Process. This guide is meant to be a complement to such documents, with tutorials and examples for how to follow these rules and how to work together with the rest of the OpenJDK Community.

There are many common use cases that aren’t detailed in the formal process. This guide suggests how to work in such cases.

I have a patch, what do I do?

In many GitHub projects the standard way to propose a change is to create a pull request (PR) and discuss the patch in the PR. For OpenJDK projects the situation is somewhat different. The JDK is used for mission critical applications and by millions of developers, the bar to contributing changes is high. Please follow the steps outlined below to make sure your change passes above the bar before creating a PR.

1. Sign the OCA

Oracle is the steward of the OpenJDK project. In order to make your patch available for review you must first sign the Oracle Contributor Agreement (OCA). This agreement gives Oracle and you as a contributor joint copyright interests in the code. You will retain your copyright while also granting those rights to Oracle.

When you sign the OCA, please make sure that you specify your GitHub user name in the Username field of the OCA. If you try to create a PR before you have signed the OCA, or if you didn’t specify your GitHub user name, you’ll get instructions telling you to do so, and the PR won’t be published until this is done. OCA registration is a manual process. Please allow for up to several days to have your OCA application processed, even though it’s normally processed swiftly.

2. Socialize your change

Once the OCA is signed, please restrain your urge to create a PR just a little while longer. In order to prepare the community for your patch, please socialize your idea on the relevant mailing lists. Almost all changes, and in particular any API changes, must go this route and have a broad agreement in place before there is any point in presenting code. To understand the criteria by which your patch is going to be judged, please read Why is My Change Rejected? below. In short, hidden constraints and assumptions, stability and quality, maintainability, compatibility, and conformance to specifications must be considered before your PR is ready to be submitted. If you don’t understand the constraints for acceptance, you might be surprised when your PR is rejected.

3. Find a sponsor

Socializing your change on the mailing lists also prevents the surprise that would otherwise make the community choke on their morning coffee when they see a huge patch in a new, unknown PR. As a new developer in the community you’ll need to make a few friends that agree with your change. There are many good reasons to make friends, but the one relevant here is that for your first changes you’ll need a sponsor to facilitate the integration of your work. The sponsor will perform any number of administrative tasks like JBS updates, additional testing, etc. It’s usual for a sponsor to also be a reviewer of a change and thus familiar with it, but it’s not a requirement.

4. Create a tracking issue in JBS

Many OpenJDK projects require a tracking issue to be filed in the JDK Bug System (JBS) before a change can be pushed. This is the case for instance for the JDK and the JDK-Updates projects. In order to get write access to JBS you need to be an Author in an OpenJDK project. For your first changes, ask your sponsor to help you create the issue.

If you continue to contribute high-quality content you’ll soon enough be eligible for OpenJDK roles in the project. First Author, and later Committer. The Committer role means you won’t need a sponsor anymore. You can read more about OpenJDK Project Roles.

5. Get acquainted with local process

Even though we strive to unify how things are done within the OpenJDK, different areas and projects in the OpenJDK may have slight variations in how they work. Some of these differences are highlighted throughout this guide, some aren’t. If you’re new to an area, make sure you understand local differences before you proceed. Ask your sponsor who should be your main point of contact through your first developer experience in the OpenJDK.

Why is my change rejected?

Java and the JDK are very popular products, and just about every Java developer out there has an idea or two for how to enhance something. And (obviously not referring to you) believe it or not, not every idea is a good idea. Even though many ideas are indeed good, we must be quite restrictive on what we actually include into the JDK. There are many reasons for this.

• Hidden constraints and assumptions. Many sections of code have constraints and assumptions that aren’t necessarily visible at first glance. This might preclude certain changes, even those that might seem obvious.

• Stability and quality. The JDK is used by millions of developers and as a widely deployed commercial product, it’s held to a high standard of quality. Changes should include tests where practical, and core tests should pass at all times. The value of the change should outweigh the risk of introducing a bug or performance regression.

• Maintainability. Any new feature or code change will need to be maintained in the JDK essentially forever, thus imposing a maintenance burden on future maintainers. The code might still be in use long after you and the people who reviewed it have moved on. New maintainers must be able to understand how to fix bugs in this code.

• Complexity. Each new feature interacts with all the existing features, which can result in geometric growth of the interactions among features if features are added unchecked. Sometimes we avoid adding a new feature, even if it seems like an obvious thing to add, if that feature would make it difficult to add a more important feature in the future.

• Adherence to specifications. Much of the JDK is governed by a series of specifications, in particular the Java Language Specification, the Java Virtual Machine Specification, and the Java API Specification (“javadocs”). All changes must be checked and tested carefully to ensure that they don’t violate these specifications.

• Javadoc comments are specifications. The Java API Specification is authored in the form of javadoc comments, so even apparently innocuous changes to comments can be quite significant. It’s not always easy to tell what comments are part of the specification and what parts are merely code comments. Briefly, documentation comments on public packages, classes, and class members of exported modules are specifications.

• Specification changes. It’s possible to change the API specifications, and this is done regularly. However, these changes require even more scrutiny than code changes. This extra review is handled by the CSR Process. Specifications are written in stylized, somewhat formal language, and they don’t simply describe what the code does. Writing specifications is a separate skill from coding.

• Compatibility. Changes should also adhere to high standards of binary, source, and behavioral compatibility. The compatibility impact of apparently innocuous changes is sometimes startling.

For reasons like these it’s quite possible that your change, even though it adds value to you, isn’t deemed to add enough value to the larger community.

Mailing Lists

The mailing lists are the key communications mechanism for all OpenJDK work. All participation in an OpenJDK project starts with joining the relevant mailing list. A subscriber to an OpenJDK mailing list is referred to as a Participant in the Bylaws. As a general recommendation we suggest to subscribe to announce, discuss, and the -dev lists covering your explicit area of interest. All OpenJDK mailing lists are found here:

mail.openjdk.java.net

The OpenJDK community is a friendly place. To keep it that way it’s important to keep a professional tone in emails and be aware that the community is global. Many different people with different backgrounds collaborate in these lists. Even though English is the required language for all lists, many Participants speak other languages as their native language. A high tolerance for non-perfect English is expected from anyone joining these lists. You’re also strongly encouraged to use your real name on the mailing lists. This adds to the professional tone of your email. Postings from anonymized mailboxes risk being seen as spam. If you do work in the OpenJDK on behalf of your employer, please also list this affiliation. If your GitHub username differs from your real name it’s also a good idea to include that to identify yourself and your actions on GitHub.

You must be a member of a list to be able to post to that list. Some lists are moderated to keep the content on topic. Each list has its own archive where you can browse older conversations on the list.

There are a few different types of lists. The list name has two parts to explain what the list is intended for, <name>-<suffix>. The name often refers to the project that owns the list or a specific area of interest that the list focuses on. The suffix is explained below. Not all projects or areas have all types of lists described here.

-dev

Technical discussions around the implementation of the project artifacts. This is also where code reviews happen.

-use

Technical discussions around the usage of the project artifacts.

-discuss

General discussions around the project. The special case discuss(at)openjdk.java.net is used for general discussions around the OpenJDK project. Discussions around new project proposals usually happens here.

-changes

Changeset notifications from the source code repositories maintained by the project.

-announce

General project announcements. These lists are tightly moderated and are expected to be low traffic. The special case announce(at)openjdk.java.net is used for announcements for the OpenJDK project.

-experts

Expert group discussions. The list is restricted; only members of the expert group can subscribe.

-observers

Open for anyone to subscribe to see what the experts are discussing and potentially to have some dialog with other non-experts. There is no guarantee that an expert is subscribed to the -observers list or will see any responses on that list.

-comments

Used by observers to directly provide feedback/comments to the experts (typically a lead will process the comments list and forward things on to the experts list).

Changing your email address

If you need to change your registered email address, or if you have any other problems with the mailing lists, please contact mailman@openjdk.java.net.

Repositories

This section describes the OpenJDK repository terminology and naming scheme. It also includes minimal instructions to acquire source from the OpenJDK repository, https://hg.openjdk.java.net/.

---

Note that source may be available from other locations, for example src.zip from a full JDK distribution. However, OpenJDK contributions must use source from the OpenJDK Mercurial repository since other source distributions may contain older code or code which differs due to licensing.

Operations which are performed repeatedly, such as creating changesets, merging, and pushing are described in Producing a Changeset.

• Terminology and Naming Scheme defines the nomenclature used by OpenJDK.
• Installing and Configuring Mercurial enumerates the required software, provides links for download, and describes basic installation and configuration.
• Cloning covers the procedure for obtaining private copies of source repositories.

This document assumes familiarity with the first two chapters of the free on-line book Mercurial: The Definitive Guide.

Terminology and Naming Scheme

The OpenJDK code base for all Projects is stored in Mercurial repositories which contain the source files and their change history. Some Projects may choose to organize their code into multiple, possibly related, Mercurial repositories. For instance, JDK 9 uses a forest of multiple related repositories which contain components of the entire JDK. Projects which are based on the JDK, such as IcedTea and Jigsaw also use this model. In contrast, Code Tools uses an unrelated repository for each tool and Graal uses only a single repository. Regardless of how a Project has chosen to store their code, each Contributor clones the repository associated with the code they are modifying.

---

Consult the Project’s documentation or mailing list to determine the appropriate repository, development conventions, and helpful tools.

This is the typical development model:

Diagram of server repos and user’s clone

A Contributor creates a clone (a local copy called “9dev”) of a read/write repository (“jdk9/dev”) which resides on the OpenJDK Mercurial server. They work on their change in the clone and locally commit a changeset. After the new changeset(s) are verified, they’re either pushed directly from the clone or exported and delivered to a Committer who can perform the push into the server repository for all to see.

---

The use of gate repositories was eliminated when the Mercurial servers were upgraded in March 2014.

The repositories use the following naming scheme:

<project>/<component_path>

where

project	::	the short name of an OpenJDK Project such as “jdk9”, “openjfx”, or “sumatra”
component_path	::	the path to a repository containing the code base as designated by the Project Lead.

Installing and Configuring Mercurial

Mercurial is a free, cross-platform, distributed source management tool. Source bundles and binary packages for Mercurial are available at https://www.selenic.com/mercurial/wiki/index.cgi. The OpenJDK repositories recommend installation of Mercurial 2.6.3 (or later). A Mercurial installation is sufficient to clone a repository. Contributors who wish to submit changes will need some additional configuration as described below.

Some Projects may recommend additional tools or scripts that help with repository manipulation and code development. For instance, in JDK 9, the utility script common/bin/hgforest.sh may be used to apply commands to all the repositories in the forest. Popular extensions for OpenJDK developers include jcheck, trees, and Mercurial Queues (mq). Note that trees is enabled on the OpenJDK Mercurial server.

Create and edit the ~/.hgrc file to minimally contain the following entry:

[ui]
username = <openjdk_username>

openjdk_username is a plain lowercase, alphanumeric token (not an e-mail address) with twelve characters or less. The first character should be alphabetic. This username will be publicly visible in all Mercurial changeset logs. It will be used to verify that the changeset author is at least an Author for the Project and that the person pushing the changeset is at least a Committer. It’s recommended that the openjdk_username be somehow related to the Author’s full name, such as the first character of the Author’s first name followed by the Author’s last name. Refer to the Becoming an Author section of the Project page for additional information.

An alphabetical list of all of the assigned openjdk_usernames may be found on the OpenJDK people list. The Census shows the structure of the OpenJDK Community.

Verifying the Configuration

After installing and configuring Mercurial, validate the configuration using the following steps.

1. Verify that Mercurial is version 2.6.3 (or newer).

   $ hg version
   Mercurial Distributed SCM (version 2.9)
   (see http://mercurial.selenic.com for more information)
   
   Copyright (C) 2005-2014 Matt Mackall and others
   This is free software; see the source for copying conditions. There is NO
   warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

2. Verify that the list of enabled extensions includes fetch and mq.

   $ hg help

3. Verify that the ~/.hgrc configuration looks correct. Minimally it should contain the following entries:

   $ hg showconfig
   ui.username=iris

At this point, it should be possible to start retrieving source from the repositories.

Cloning

With Mercurial each developer works with a clone of the repository which is a snapshot of the files at the time the clone was taken. To update the clone, see Producing a Changeset.

… a Sandbox Repository

In addition to the Project repositories, there are some test repositories that may be used to run test commands against Mercurial without fear of causing damage to development source. Use them freely but with discretion; content in them may be deleted at any time.

$ mkdir sandbox; cd sandbox
$ hg clone http://hg.openjdk.java.net/sandbox/box
destination directory: box
requesting all changes
adding changesets
adding manifests
adding file changes
added 23 changesets with 24 changes to 5 files
4 files updated, 0 files merged, 0 files removed, 0 files unresolved
$ du -s box
46      box

… a Forest

If a Project uses a forest, It’s strongly recommended for developers to clone an entire forest, rather than a single repository. This is the only means to ensure consistency in builds. The following examples illustrate two alternatives for cloning the entire jdk9/dev forest into the directory 9dev.

1. To clone the forest using the trees extension just use tclone:

   $ hg tclone http://hg.openjdk.java.net/jdk9/dev 9dev

2. To clone the forest using get_source.sh, first clone the main tree:

   $ hg clone http://hg.openjdk.java.net/jdk9/dev 9dev
   requesting all changes
   adding changesets
   adding manifests
   adding file changes
   added 997 changesets with 1477 changes to 138 files
   updating to branch default
   82 files updated, 0 files merged, 0 files removed, 0 files unresolved

   Then clone the repositories in the forest:

   $ cd 9dev
   $ sh ./get_source.sh

Regardless of how the forest was cloned, this is the resulting populated forest.

$ du -s
934532  .
$ ls
ASSEMBLY_EXCEPTION  hotspot    LICENSE   README-builds.html
common              jaxp       make      test
configure           jaxws      Makefile  THIRD_PARTY_README
corba               jdk        nashorn
get_source.sh       langtools  README

… a Single Repository

If the source for the Project is contained within a single repository or reading a limited portion of the source is the only goal, it’s possible to clone a single repository (even if it’s part of a forest). For instance, this example shows how to clone the langtools repository from jdk9/dev into the default destination directory.

$ hg clone http://hg.openjdk.java.net/jdk9/dev/langtools
destination directory: langtools
requesting all changes
adding changesets
adding manifests
adding file changes
added 2289 changesets with 21194 changes to 7004 files
updating to branch default
6212 files updated, 0 files merged, 0 files removed, 0 files unresolved
$ du -s langtools
84396   langtools

Code Conventions

JBS - JDK Bug System

JBS is an issue tracker used by many OpenJDK projects.

Filing a Bug

When a new failure is found in the JDK a bug should be filed to describe and track the issue. Depending on your role in the OpenJDK you can either use the Bug Report Tool or, if you are Author in an OpenJDK Project, report the bug directly in the JDK Bug System. Try to make the bug report as complete as possible to make it easier to triage and investigate the bug.

It’s not the reporter’s responsibility to set a correct priority, but a qualified guess is always better than a default value. To help with setting the right priority consider things like how the bug impacts the product and our testing, how likely is it that the bug triggers, how difficult is it to work around the bug if it’s not fixed soon, and whether it’s a recent regression, since that may break existing applications. Regressions are often higher priority than long standing bugs and may block a release if not fixed.

A few things to keep in mind when filing a new bug:

• Before filing a bug, verify that there isn’t already a bug filed for this issue.
• If you suspect that the bug is a vulnerability, don’t file a JBS issue. Instead send your bugreport to vuln-dev@openjdk.java.net
• Make a reasonable attempt to narrow down which build or release the failure first appeared in.
• Add relevant labels like intermittent, regression, noreg-self, ‘tier1’ etc.
• Set affects version to the JDK version(s) where the failure was seen.
  • If the failure is found in an update train of the JDK (e.g. 11.0.x), please make an effort to see if the bug is also present in mainline.
• Set priority (see above)
• In the description, always include (if possible):
  • full name of the failing tests
  • error messages
  • assert messages
  • stack trace
  • command line information
  • relevant information from the logs
• If the failure isn’t reproducible with an existing OpenJDK test, attach a reproducer if possible.
• Only set CPU and/or OS fields if the bug ONLY happens on that particular platform.
• Always file separate bugs for different issues.
  • If two crashes looks related but not similar enough to for sure be the same, it’s easier to close a bug as a duplicate than it is to extract the relevant info from a bug to create a new one later.

To find out which component to use for different bugs, consult the directory to area mapping.

How to fix an incorrect backport creation

If a main bug is targeted to a release and the fix is pushed to a different release, then a backport bug is automatically created. Usually this is a “good thing”, e.g., when you are backporting a fix to an earlier release, but not always… If the main bug is targeted to a later release (due to schedule planning), but someone finds the time to fix that bug in the current release, then the bug should be retargeted to the current release before pushing the fix. However, sometimes we forget to do that.

Here is how to fix that:

---

In this example a fix was pushed to JDK N (a.k.a. the current release) while the JBS bug was targeted to JDK N+1 (a.k.a. a future release).

1. Reopen the backport bug that was created automatically
   • Use a comment like the following (in the reopen dialog):

   Fix was pushed while main bug was targeted to 'N+1'. Reset the main bug to fixed in 'N', reset this bug to fix in 'N+1' and closed as 'Not An Issue' since JDK N+1 will automatically get this fix from JDK N.

   • Change the ‘Fix Version/s’ from ‘N’ to ‘N+1’.
   • Close the backport bug as “Not an Issue”.
2. Clean up the main bug
   • Copy the open push notification comment from the backport bug to the main bug, e.g.:

   Changeset: 12345678
   Author: Duke <duke@openjdk.org>
   Date: 2020-10-23 15:37:46 +0000
   URL: https://git.openjdk.java.net/jdk/commit/12345678

   • Add a comment like the following to the main bug:

   Fix was pushed while main bug was targeted to 'N+1'. Reset the main bug to fixed in 'N' and copied the Robo Duke entry here.

   • Reset the main bug ‘Fix Version/s’ from ‘N+1’ to ‘N’.
   • Resolve the main bug as “Fixed” in build “team” or in build “master” depending on where the fix was pushed. Pushes to ‘openjdk/jdk’ are fixed in build “master” and pushes to project repositories are fixed in build “team”.

Resolved - Incomplete

To resolve an issue as Incomplete is JBS lingo for “Need More Information”. An issue that is Resolved - Incomplete is not closed but more information is needed to be able to work on it. If no more information is obtained within reasonable time the issue should be closed (Closed - Incomplete). Closing a resolved issue is done using the Verify option.

JBS Label Dictionary

This table contains some frequently used JBS labels and their meaning. Please help keeping this dictionary up to date by adding your favorite labels. This table doesn’t dictate how to use labels, but rather document how they are used. That said, obviously it will help everyone if we try to follow a common standard and use similar labels in the same way across all entities that use JBS.

Labels are an open namespace, which means that anyone can create new labels at any time. In order to avoid confusion, however, it’s best to reuse existing labels where possible. This can be done by editing the “labels” field of a bug and entering the first few characters of the label you want to add. JIRA will pop up an autocomplete window with existing labels that match that prefix. Then choose one of the existing labels. Using the autocomplete window is preferable to typing the whole label name (even if you’re a good typist) because it’s easy for minor spelling errors to creep in, which can inadvertently introduce multiple labels with spurious spelling variations.

---

Labels are case sensitive

When using labels in Jira gadgets (like pie charts, heat maps, and statistics tables) Jira will be case sensitive and treat e.g. OpenJDK and openjdk as two different labels. Searching however is case insensitive. This means that if you group a set of issues in a gadget based on a label, and then click one of the groups to see the list of issues, that list will contain more results than the gadget if there are usages of the label with different casing. This can be very confusing and for this reason the recommendation is to stick with the commonly used case for all labels, regardless of your personal taste for upper or lower case letters. Most labels are lower case only, but there are examples where upper case letters are used in the most common version of a label. Use of the autocomplete popup window (described above) when adding labels will avoid inadvertent introduction of labels with differing case.

Fixing a Bug

This is the list of steps which should be performed when fixing a small bug. Small bugs include typos in code or specification, algorithm improvements for correctness or performance, and code changes required to correctly implement the specification.

---

Some steps refer to operations which can’t be performed directly without the assistance of a Project Committer. For example, any changes to the bug database fall into this category. Since these steps are required, Contributors are urged to work with their Sponsors to complete these tasks.

For the purposes of brevity this document will use the term “bug” to refer to both bugs and enhancements unless otherwise noted. Hence “fix for a bug” could also imply “implementation for an enhancement”.

1. Discuss the intended change

   Send an e-mail to the appropriate development mailing list for the Project that maintains the code. The e-mail should have a subject line of the form:

   6543210: My favorite bug

   where 6543210 is replaced with the actual bug id number or “[NEW BUG]” if the bug id isn’t known and My favorite bug is replaced with the bug’s summary. The message should describe the intended change, which components may be affected, and any other risks or concerns.

2. Does a bug id exist for the work?

   Yes

   Continue

   No

   Create a bug in an appropriate component/sub-component.

3. Set the bug status to “Open”

   This communicates intent to fix the bug to other members of the Project. It also sets the expectation for downstream teams such as SQE and JCK that the bug will be fixed in an upcoming integration.

4. Does the fix for the bug require a specification change, directly affect an external interface, or otherwise have a compatibility impact?

   Yes

   Submission of a CSR request is required. The CSR must be approved before the bug fix is pushed to a feature release or update release repository. The work may begin concurrently with the CSR review, but may need to be modified in response to CSR feedback.

   No

   Continue

5. Fix the bug

   Assuming that the development team approves of the intended approach, begin working on the code using the latest source available from the appropriate OpenJDK Project repository.

6. [Is it possible to write a test to detect the bug?]

   Yes

   For bugs, provide a jtreg regression test as part of the changeset. For enhancements that directly affect one or more exported interfaces, add an adequate set of jtreg unit tests as part of the changeset. By convention all regression and unit tests should contain a @bug tag referencing at least one bugid.

   An entirely new test (or tests) may not be required. For example, if the bug is an existing regression test failure, then when fixing the bug you should just add the new bug ID to the list of space-delimited bugs in the @bug tag of the failing regression test, even if the test didn’t need to be updated.

   No

   An explanation for why a test is unnecessary or infeasible is required. Such an explanation is recorded by adding a label, and possibly a comment, to the bug report. The label has the prefix noreg for regression tests and nounit for unit tests. The suffix of the label is described in detail in the JBS Label Dictionary

7. Is modification of shared Java code needed?

   Yes

   It’s often sufficient to build and test on a single platform, but sometimes it’s not. Use discretion.

   No

   Continue

8. Is modification of shared C code needed?

   Yes

   Build and test on at least one instance of all three of the supported operating systems (Solaris, Linux, and Windows).

   No

   Continue

9. Is modification of C or Java platform-specific code needed?

   Yes

   Build and test on all relevant platforms. Code under src/solaris builds on Solaris, Linux, and MacOS X despite its name.

   No

   Continue

10. Run relevant regression and unit tests on all relevant platforms

    These include tests for external interfaces as well as other kinds of tests, e.g., HotSpot tests that use internal verification mechanisms.

11. Run relevant JCK tests on all relevant platforms

    Running JCK tests is particularly important if the change may have unexpected side-effects.

12. Request a review of the changes by sending an e-mail to the development alias

    A patch can be submitted as described in Contributing. Alternatively, a “webrev” may be generated and uploaded to the community code review server. The complete webrev generation and upload procedure is described at https://cr.openjdk.java.net.

    Changeset pushes before the Feature Complete require at least one Reviewer; pushes after the Feature Complete require at least two Reviewers. In either case, the more the merrier. Some teams may require more Reviewers. Check with members of the Project.

    Reviewers should examine not only the code being added or changed but also the relevant unit or regression tests.

    A change may require multiple Reviewers because it affects multiple areas. Reviewers should be aware that they take full responsibility for the appropriateness and correctness of any changes in their area of expertise. If something goes wrong (e.g., the build breaks) and the change's author is unavailable, they may be asked to deal with the problem. Potential Reviewers are encouraged to refuse to review code for which they aren’t qualified.

13. Create a changeset

    Follow the instructions in Producing a Changeset.

14. Update the bug content

    Bug descriptions and comments should be written in a professional manner.

15. Push the changeset into the Project’s forest

    Follow the instructions in Producing a Changeset. If working with a Sponsor, send the changeset to the development mailing list so that they can handle the final push.

    The push will trigger a update to the bug which will make the following changes:

    • Set the bug’s “Status” to “Resolved” and “Resolution to”Fixed".
    • Set the bug’s “Fix Version/s” to an appropriate release.
    • Set the bug’s “Resolved in Build” to “team”.
    • Add a Comment containing a reference to the changeset.

Congratulations! Your changeset will now make its way towards a promoted build. When the changeset becomes part of a promoted build, the bug’s “Resolved in Build” will have a value of "b[1-9][0-9]*" to indicate the build number.

Testing the JDK

In addition to your own Java applications, OpenJDK have support for two test frameworks, JTReg and GTest. JTReg is a Java regression test framework that is used for most of the tests that are included in the OpenJDK source repository. The Google Test (GTest) framework is intended for unit testing of the C++ native code. Currently only JVM testing is supported by the GTest framework. Other areas use JTReg for unit testing of C++ code.

This section provides a brief summary of how to get started with testing in OpenJDK. For more information on configuration and how to use the OpenJDK test framework, a.k.a. “run-test framework”, see doc/testing.md.

In general all changes should come with a regression test so if you’re writing product code you should also be writing test code. There are a few examples where it doesn’t make sence to write an explicit regression test. These should be tagged in JBS with one of the noreg-labels.

A few key items to think about when writing a regression test:

• A regression test should execute fast - a few seconds at most
• The test should only test the desired functionality - if you have several features to test, write more tests
• The test should pass reliably on all supported platforms - watch out for platform-specific differences such as path separators
• Binary files shouldn’t be checked in, if your test needs to use one, the test should create it in some fashion
• Avoid shell scripts and relying on external commands as much as possible

The JTReg documentation has a section on how to write good JTReg tests.

JTReg

In-depth documentation about the JTReg framework is found here: JTReg harness. JTReg itself is available in the Code Tools Project.

Below is a small example of a JTReg test. It’s a clean Java class with a main method that is called from the test harness. If the test fails we throw a RuntimeException. This is picked up by the harness and is reported as a test failure. Try to always write a meaningful message in the exception. One that actually helps with understanding what went wrong once the test fails.

/*
 * @test
 * @summary Make sure feature X handles Y correctly
 * @run main TestXY
 */
public class TestXY {
    public static void main(String[] args) throws Exception {
        var result = X.y();
        if (result != expected_result) {
            throw new RuntimeException("X.y() gave " + result + ", expexted " + expected_result);
        }
    }
}

This example only utilizes three JTReg specific tags, @test, @summary, and @run. @test simply tells JTReg that this class is a test, and @summary provides a description of the test. @run tells JTReg how to execute the test. In this case we simply tell JTReg to execute the main method of the class TestXY. @run isn’t strictly necessary for JTReg to execute the test, an implicit @run tag will be added if none exists. However, for clarity and in order to avoid bugs it’s recommended to always explicitly use the @run tag.

There are several other tags that can be used in JTReg tests. You can for instance associate the test with a specific bug that this test is a regression test for.

@bug 7000001

Or you can specify a number of requirements that must be fulfilled for JTReg to execute the test.

@requires docker.support
@requires os.family != ”windows”
@requires os.maxMemory > 3G
@requires os.arch=="x86_64" | os.arch=="amd64"

You can also specify if the test requires specific modules, and you can specify command line flags and run the test in several different ways.

@modules java.base/jdk.internal.misc
@run main/othervm -Xmx128m TestXY

Note that you can have several @run tags in the same test with different command line options.

JTReg also have support for labeling tests with keys using the @key tag. These keywords can then be used to filter the test selection. For instance if you have a UI test which needs to display a window you’ll want to make sure the test harness doesn’t try to run this test on a system which doesn’t support headful tests. You do this by specifying

@key headful

Another example is @key randomness that should be used to indicate that a test is using randomness - i.e. is intentionally non-deterministic.

There are many other keywords in use and their usage may differ between areas in the JDK. Make sure you understand the conventions for the particular area you are testing since these are just examples.

The JTReg documentation provides information on many more tags like these.

The compiler group has a section in their wiki with Guidelines for “langtools” tests.

Running OpenJDK JTReg Tests

When configuring the OpenJDK build you can tell it where your JTReg installation is located. When providing this information you can later run make run-test to execute JTReg tests.

sh ./configure --with-jtreg=/path/to/jtreg
make run-test TEST=tier1

In the OpenJDK source tree you can find a directory called test. There are a large number of tests in this directory that are written to be used with JTReg.

make run-test TEST=test/jdk/java/lang/String/

You can also run JTReg without invoking make. In this case you’ll need to tell JTReg which JDK to test.

jtreg -jdk:/path/to/jdk /path/to/test

GTest

As mentioned the Google test framework is mainly used for C++ unit tests. There are several of these in the test/hotspot directory. Currently, only the C++ code in the JVM area is supported by the OpenJDK GTest framework. The tests can be run without starting the JVM, which enables testing of JVM data structures that would be fragile to play with in a running JVM.

static int demo_comparator(int a, int b) {
  if (a == b) {
    return 0;
  }
  if (a < b) {
    return -1;
  }
  return 1;
}

TEST(Demo, quicksort) {
  int test_array[] = {7,1,5,3,6,9,8,2,4,0};
  int expected_array[] = {0,1,2,3,4,5,6,7,8,9};

  QuickSort::sort(test_array, 10, demo_comparator, false);
  for (int i = 0; i < 10; i++) {
    ASSERT_EQ(expected_array[i], test_array[i]);
  }
}

ASSERT_EQ is one example of an assertion that can be used in the test. Below are a few other examples. A full list is found in the Google Test Documentation.

ASSERT_TRUE(condition);
ASSERT_FALSE(condition);
EXPECT_EQ(expected, actual);
EXPECT_LT(val1, val2);
EXPECT_STREQ(expected_str, actual_str);

ASSERT is a fatal assertion and will interrupt execution of the current sub-routine. EXPECT is a nonfatal assertion and will report the error but continues to run the test. All assertions have both an ASSERT and an EXPECT variant.

For more information on how to write good GTests in HotSpot, see doc/hotspot-unit-tests.md.

Running OpenJDK GTests

When configuring the OpenJDK build you can tell it where your GTest installation is located. Once configured, use make to run GTests.

sh ./configure --with-gtest=/path/to/gtest
make test TEST=gtest

You can also use a regular expression to filter which tests to run:

make test TEST=gtest:code.*:os.*
make test TEST=gtest:$X/$variant

The second example above runs tests which match the regexp $X.* on a specific variant of the JVM. The variant is one of client, server, etc.

Excluding a Test

Sometimes tests break. It could be e.g. due to bugs in the test itself, due to changed functionality in the code that the test is testing, or changes in the environment where the test is executed. While working on a fix, it can be useful to stop the test from being executed in everyone else’s testing to reduce noise, especially if the test is expected to fail for more than a day. There are two ways to stop a test from being run in standard test runs: ProblemListing and using the @ignore keyword. Removing tests isn’t the standard way to remove a failure. A failing test is often a regression and should ideally be handled with high urgency.

I’ll say it right away so that it’s not forgotten at the end: Remember to remove the JBS id from the ProblemList or the test when the bug is closed. This is especially easy to forget if a bug is closed as a duplicate or ‘Will Not Fix’. jcheck will report an error and prohibit a push if a PR is created for an issue that is found in a ProblemList if the fix doesn’t remove the bug ID from the ProblemList.

ProblemListing jtreg tests

ProblemListing should be used for a short term exclusion while a test is being fixed, and for the exclusion of intermittently failing tests that cause too much noise, but can still be useful to run on an ad-hoc basis. ProblemListing is done in the file ProblemList.txt. There are actually several ProblemList files to choose from. Their location and name hint about what area or feature each file belongs to. Each file has sections for different components. All ProblemList files complement each other to build the total set of tests to exclude in JTReg runs.

test/hotspot/jtreg/ProblemList.txt
test/hotspot/jtreg/ProblemList-aot.txt
test/hotspot/jtreg/ProblemList-graal.txt
test/hotspot/jtreg/ProblemList-non-cds-mode.txt
test/hotspot/jtreg/ProblemList-Xcomp.txt
test/hotspot/jtreg/ProblemList-zgc.txt
test/jaxp/ProblemList.txt
test/jdk/ProblemList.txt
test/jdk/ProblemList-aot.txt
test/jdk/ProblemList-graal.txt
test/jdk/ProblemList-Xcomp.txt
test/langtools/ProblemList.txt
test/langtools/ProblemList-graal.txt
test/lib-test/ProblemList.txt

Use the suitable ProblemList and add a line like this in the proper section:

foo/bar/MyTest.java                        4711   windows-all

In this example, MyTest.java is ProblemListed on windows, tracked by bug JDK-4711.

Currently there’s no support for multiple lines for the same test. For this reason it’s important to always make sure there’s no existing entry for the test before adding a new one, as multiple entries might lead to unexpected results, e.g.

foo/bar/MyTest.java                        4710   generic-all
...
foo/bar/MyTest.java                        4711   windows-all

This would lead to sun.tools.jcmd.MyTest.java being ProblemListed only on windows-all. The proper way to write this is:

foo/bar/MyTest.java                        4710,4711   generic-all,windows-all

Although windows-all isn’t strictly required in this example, it’s preferable to specify platforms for each bugid (unless they are all generic-all), this makes it easier to remove one of the bugs from the list.

ProblemListing some, but not all, test cases in a file

Some tests contain several test cases and there may be a need to ProblemList only a few of them. To do this use the full test name, i.e. <filename> + # + <test case id>, where test case id can be specified in the test header. If no id is specified each test case can be referenced with id + ordinary number of the test case in the test file.

Let’s assume we have four test cases in foo/bar/MyTest.java:

/* @test */
/* @test id=fancy_name */
/* @test */
/* @test */

A ProblemList entry that excludes the first, second, and third test case would look like this:

foo/bar/MyTest.java#id0          4720  generic-all
foo/bar/MyTest.java#fancy_name   4721  generic-all
foo/bar/MyTest.java#id2          4722  generic-all

Due to an issue described in CODETOOLS-7902712 tests that contains more than one @test must actually use this way to specify all test cases if all of them should be ProblemListed. Specifying just the test name will not work.

Running ProblemListed tests

To run ad-hoc runs of ProblemListed tests use RUN_PROBLEM_LISTS=true.

make test TEST=... JTREG=RUN_PROBLEM_LISTS=true

Exclude jtreg tests using @ignore

The @ignore keyword is used in the test source code. This is mainly used for tests that are so broken that they may be harmful or useless, and is less common than ProblemListing. Examples can be tests that don’t compile because something changed in the platform; or a test which might remove your /etc/shadow. Use @ignore with a bug reference in the test case to prevent the test from being run.

/**
 *  @test
 *  @ignore 4711
 *

In this example, MyTest.java is excluded, tracked by bug JDK-4711. @ignore should always be placed directly before the first @run line in the test.

Dealing with JBS bugs for test exclusion

ProblemListing and @ignore-ing are done in the JDK source tree, that means a check-in into the repository is needed. This in turn means that a unique JBS issue and a code review are needed. This is a good thing since it makes test problems visible.

• Code review: ProblemListing a test is considered a trivial change.
• JBS issue: A JBS issue is obviously created for the bug that caused the failure, we call this the main issue. To exclude the test, create a subtask to the main issue. Also add the label problemlist to the main issue.

The fix for the main issue should remove the test from the ProblemList or remove the @ignore keyword from the test.

Triage excluded issues

After a failure is handled by excluding a test, the main JBS issue should be re-triaged and possibly given a new priority. This should be handled by the standard triage process. A test exclusion results in an outage in our testing. This outage should be taken into consideration when triaging, in addition to the impact of the bug itself.

Producing a Changeset

This section is confined to the actual Mercurial mechanics required to produce a changeset:

• Setting a JDK User Name reminds the user to confirm proper configuration.
• Creating includes instructions for the required format of a changeset comment and describes how to commit files to a changeset.
• Merging describes how to pull changes from a parent forest or clone and incorporate the changes into the current working set of files.
• Pushing covers configuring ssh, setting the default-push path, and pushing changesets.

Setting a JDK User Name

Ensure that ui.username has a value in the ~/.hgrc file as described in Verifying the Configuration.

Creating

The timing for creating a changeset is important. Creating the changeset long before it gets pushed into the parent repository may require complex merges. If a changeset is created before sufficient review or testing, a rollback may be required and a new changeset may be required to correct previous mistakes. The mq extension is recommended for managing changes before they become committed to a changeset.

In the examples below, the script common/bin/hgforest.sh can be used to apply the Mercurial command to all the repositories in the forest. So when you see hg, if you are dealing with one repository, just use “hg”, if it’s a forest, use “sh common/bin/hgforest.sh”.

Each repository in the forest is managed independently. After editing files in the individual cloned repositories of the forest, the hg status command may be used to see the changes in a single repository.

$ hg root
/u/iris/sandbox/box
$ hg status
? duke/images/DukeTubbingSmall.png
$ hg add duke/images/DukeTubbingSmall.png
$ hg status
A duke/images/DukeTubbingSmall.png

To see changes made to the repositories use hg status:

$ hg status
[.]
A duke/images/DukeTubbingSmall.png

In this example, the repository was previously cloned as described in Cloning a Sandbox Repository. A new file DukeTubbingSmall.png was added to a new subdirectory.

Formatting a Changeset Comment

A single change is described by a block of text of the following form:

<bugid>: <synopsis-of-symptom>
Summary: <summary-of-code-change>
Reviewed-by: <reviewer>+
Contributed-by: <contributor-email>

There may be more than one bugid line, but there must be at least one.

The summary line is optional, but authors are strongly encouraged to include one if the nature of the change isn’t obvious from the synopsis. It’s just one line, meant to give the reader a clue as to how the code changed. A more complete description of the change belongs in the bug report.

A reviewed-by line is required. Reviewers must have the ability to deal with any adverse consequences of the change, and so must themselves be authors. They are therefore identified by their OpenJDK usernames rather than full e-mail addresses.

The contributed-by line is optional. If present, it’s a list of comma-separated email addresses. It should be included only when the author or authors of the change don’t have commit rights to the target repository and thus would not otherwise receive acknowledgment.

There will be exceptions for merge changesets, tag changesets, etc.

Example:

1234567: NPE thrown on FileInputStream("")
Summary: Rewrite precondition-checking code in io.c
Reviewed-by: mr
Contributed-by: Ben Bitdiddle <ben at bits.org>

If a changeset contains multiple unrelated changes (this is frowned upon, but may happen from time to time) then its comment will contain multiple blocks of the above form, separated by blank lines.

The required format of the comments will be enforced whenever the changeset is pushed into the JDK master or team repository forests. Other Projects may copy these conventions, adopt some other conventions, or have no conventions, depending upon their goals.

Committing a Changeset

The following commands commit all of the changes in a repository to a changeset.

$ cat ../message
1111111: Missing Duke gif
Summary:  Add missing file
Reviewed-by: iag
$ hg commit -l ../message
$ hg toutgoing
[.]
comparing with http://hg.openjdk.java.net/sandbox/box
searching for changes
changeset:   23:fb12953f3a35
tag:         tip
user:        iris
date:        Wed Dec 12 21:05:59 2007 -0800
summary:     1111111: Missing Duke gif

Merging

It’s often necessary to merge local changes with those made in the parent repositories. The first step in a merge process is to retrieve (or pull) the collection of changesets which have been pushed since the last merge or initial clone. If there if there are merge conflicts, then they must be resolved. Chapter 3 of the Mercurial book contains detailed information on the merging process.

There are two basic ways to update the working set files in the repositories:

Option 1: hg pull

One way to merge the parent repository with the working set of files is to use hg pull all by itself. This option allows merging off-line or at a later time.

$ hg pull
[.]
pulling from http://hg.openjdk.java.net/sandbox/box
searching for changes
no changes found

In Mercurial, pulling changesets will not update or merge into the working set of files. To update the clone, run hg update. If the update reports conflicts, run hg merge to resolve them.

Option 2: hg fetch

Alternatively, use hg fetch to pull the changes, update the working set files, and create simple merge changesets as necessary. The fetch extension is distributed with Mercurial but needs to be enabled. Edit the .hgrc to include the following entries:

[extensions]
fetch=

Once the fetch extension has been enabled, hg fetch may be invoked as follows:

$ hg fetch
[.]
pulling from http://hg.openjdk.java.net/sandbox/box
searching for changes
no changes found

---

Actual file merging will be done with the selected Mercurial merging tool see MergeProgram for the details on how to define the selected merge tool in ~/.hgrc.

Pushing

In order to push changesets into the parent repository, some additional configuration is required. The following sections describe the operations that will be performed by users with push access.

Generating an SSH Key

All pushes require an ssh key which must be installed on the Mercurial server. The ssh-keygen command generates an ssh key. The -b option overrides the default number of bits for the key. Allow a few minutes to generate a 4096 bit key; a key of at least 2048 bits is recommended. While it’s possible to use ssh without a passphrase, this is strongly discouraged. Empty or insecure passphrases may be reset using ssh-keygen -p; this doesn’t change the keys.

$ ssh-keygen -t rsa -b 4096
Enter file in which to save the key(/u/iris/.ssh/id_rsa):
Generating public/private rsa key pair.
Enter passphrase(empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /u/iris/.ssh/id_rsa.
Your public key has been saved in /u/iris/.ssh/id_rsa.pub.
The key fingerprint is:
md5 4096 c2:b7:00:e6:4b:da:ea:ec:32:30:f5:bd:12:26:04:83 iris@duke
The key's randomart image is:
+--[ RSA 4096]----+
|    E.=          |
|     . *         |
|      o .   .    |
|         + o     |
|        S + .    |
|       .   + .   |
|        + + +..  |
|       * . oo+.  |
|      o . .o..   |
+-----------------+

The ~/.ssh/id_rsa.pub is a text file containing the public ssh key. This file should be mailed as an attachment along with the JDK username to keys(at)openjdk.java.net. An administrator will install your key on the server and notify you on completion. This process may take a couple of days.

---

Users behind a SOCKS firewall can add a directive to the ~/.ssh/config file to connect to the OpenJDK Mercurial server:

Host *.openjdk.java.net
ProxyCommand /usr/lib/ssh/ssh-socks5-proxy-connect -h [socks_proxy_address] %h %p

See the ssh-socks5-proxy-connect man page and ssh-config man page for more information. Other systems may require proxy access via other programs. Some Linux distributions provide the corkscrew package which provides ssh access through HTTP proxies.

It’s recommended that all users check with their network administrators before installing any kind of TCP forwarding tool on their network. Many corporations and institutions have strict security policies in this area.

SSH Shortcuts

The following section provides some tips for improving the usability of ssh-related operations.

• Using SSH in multiple shells

  To avoid having to constantly type in the passphrase, use the ssh-agent on your local client to cache your pashphrase:

  $ eval `ssh-agent`
  Agent pid 17450
  $ ssh-add
  Enter passphrase for /u/iris/.ssh/id_rsa:
  Identity added: /u/iris/.ssh/id_rsa(/u/iris/.ssh/id_rsa)

  The same ssh-agent process can be shared with multiple shells. There are various ways to do this. Bash users can accomplish this with the following code in .bashrc:

  if [ "$PS1" -a -d $HOME/.ssh ]; then
    if [ "x$SSH_AUTH_SOCK" = x ]; then
      eval `ssh-agent | grep -v 'echo Agent pid'`
      ssh-add
      trap "echo Killing SSH agent $SSH_AGENT_PID; kill $SSH_AGENT_PID" 0
    fi
  fi

  For secure operation, only start an ssh-agent when needed and kill it off when the shell completes. Test this by running ssh 'hostname' echo hello multiple times.

• Logging in without a password

  To avoid needing to constantly type in the password, add the public key to the list of ssh authorized keys.

  $ cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys
  $ chmod 600 ~/.ssh/authorized_keys

Setting the default-push Path to the Server Repositories

This is the typical development model:

Diagram of server repos and user’s clone

Changesets need to be pushed via ssh to the read/write repository which resides on the OpenJDK Mercurial server. The easiest way to do this is to have each repository define the “default-push” path in every repository’s .hg/hgrc file. The .hg/hgrc file in isn’t a managed file - it’s private to the repository. The following example defines the “default” and “default-push” paths for clones of the jdk9/dev team repository.

[paths]
default = http://hg.openjdk.java.net/jdk9/dev
default-push = ssh://<JDK_username>@hg.openjdk.java.net/jdk9/dev

Given a JDK_username this simple script will attempt to do this for all the repositories:

#!/bin/sh
username=$1
hgdirs="`find . -type d -name .hg`"
for i in ${hgdirs}; do
  d="`dirname ${i}`"
  defpush="`(cd ${d} && hg paths default-push 2> /dev/null)`"
  if [ "${defpush}" = "" ] ; then
    defpath="`(cd ${d} && hg paths default 2> /dev/null)`"
    if [ "${defpath}" != "" ] ; then
      defpush="`echo ${defpath} | sed -e 's@http://\([^/]*/[^/]*/[^/]*\)/\(.*\)@ssh://$username\@\1/\2@'`"
      cp ${i}/hgrc ${i}/hgrc.orig
      echo "default-push = ${defpush}" >> ${i}/hgrc
      echo "Added default-push: ${defpush}"
    fi
  fi
done
for i in ${hgdirs}; do
  d="`dirname ${i}`"
  echo "(cd ${d} && hg paths)"
  (cd ${d} && hg paths)
done
exit 0

Pushing a Changeset

Committers can use the hg push command to propagate changesets into the repositories.

Most developers will only find a need to create changesets in one or two repositories. However, it’s important that before any changesets are pushed, the corresponding forest pull and merge with the destination forest be performed; otherwise there is a risk of breaking the build.

$ hg push

After the push has been accepted, an automatic e-mail notification will be sent to the mailing list associated with the repository. In most cases notifications are sent to the Project’s -dev mailing list. Some Projects with high traffic -dev mailing lists use a dedicated -changes list for notifications.

---

Who has push access?

All of a Project’s Committers can push to all of the the Project’s repositories.

Some Projects may chose to restrict the set of Committers with push to key repositories. For instance, JDK Release Projects restrict push access to MASTER repositories to Committers who are either integrators or members of the Release Engineering Team.

Refer to the Nominating a Contributor or Author to be a Committer section of the Project page for information about becoming a Project Committer.

Backing Out a Change

If a change causes a regression that can’t be fixed within reasonable time the best way to handle the regression can be to back out the change. Backing out means that the inverse (anti-delta) of the change is pushed to effectively undo the change in the repository. There are two parts to this task, how to do the bookkeeping in JBS, and how to do the actual backout in mercurial.

The backout is a regular change and will have to go through the standard code review process, but is considered a trivial change. The rationale is that a backout is usually urgent in nature and the change itself is automatically created by hg, and reviewed by the person who is performing the backout, so even though only one additional Reviewer is required the change will in practice get two reviews.

How to work with JBS when a change is backed out

1. Close the original JBS issue (O).
   • “Verify” the issue and choose “Fix Failed”.
2. If the intention is to fix the change and submit it again, create a redo-issue (R) to track that the work still needs to be done.
   • Clone (O) and add the prefix [REDO] on the summary - the clone becomes the redo-issue (R).
   • Make sure relevant information is brought to (R).
   • Remember that comments aren’t brought over when cloning.
3. Create a backout-issue (B):
   • Alternative 1 - the regression is identified directly.
     • Create a sub-task to (R) with the same summary, prefix with [BACKOUT].
   • Alternative 2 - an investigation issue is created (I), and during the investigation backing out the change is identified as the best solution.
     • Use the investigation issue (I) for the backout.
     • Change summary of (I) to the same as (O) and prefix with [BACKOUT].
     • Move and change type of (I) to become a sub-task of (R).
   • Alternative 3 - no redo issue was created.
     • Create a backout-issue (B) with the same summary as (O), prefix with [BACKOUT].
     • Link (B) and (O).

ProblemList entries and @ignore keywords will continue to point to the original bug (unless updated at back out). This is accepted since there is a clone link to follow.

How to work with mercurial when a change is backed out

In order to backout a change, the hg backout command is recommended, which essentially applies the anti delta of the change. Make sure you perform the backout in the most upstream repostiory the change has escaped to.

hg backout [OPTION]... [-r] REV

reverse effect of earlier changeset

    Prepare a new changeset with the effect of REV undone in the current
    working directory.

    If REV is the parent of the working directory, then this new changeset is
    committed automatically. Otherwise, hg needs to merge the changes and the
    merged result is left uncommitted.

Code Owners

This list is intended to make it easier to identify which email list to include in code reviews when making changes in different areas. The list may also help when assigning bugs based on which code they are found in. Please note that some directories may have been created or removed between releases. The intention here is to include directories that exists in mainline, LTS releases and other releases (post JDK 9) commonly being updated.

Area mailing lists

• Build: build-dev@openjdk.java.net
• Client
  • AWT: awt-dev@openjdk.java.net
  • Beans: beans-dev@openjdk.java.net
  • Java 2D: 2d-dev@openjdk.java.net
  • Java FX: openjfx-dev@openjdk.java.net
  • jpackage: core-libs-dev@openjdk.java.net
  • Sound: sound-dev@openjdk.java.net
  • Swing: swing-dev@openjdk.java.net
• Core Libs: core-libs-dev@openjdk.java.net
  • Net: net-dev@openjdk.java.net
  • NIO: nio-dev@openjdk.java.net
• HotSpot: hotspot-dev@openjdk.java.net
  • Compiler: hotspot-compiler-dev@openjdk.java.net
  • GC: hotspot-gc-dev@openjdk.java.net
  • Runtime: hotspot-runtime-dev@openjdk.java.net
  • JFR: hotspot-jfr-dev@openjdk.java.net
  • Serviceability: serviceability-dev@openjdk.java.net
• I18n: i18n-dev@openjdk.java.net
• LangTools
  • Amber Project: amber-dev@openjdk.java.net
  • Javac: compiler-dev@openjdk.java.net
  • Javadoc: javadoc-dev@openjdk.java.net
  • JShell: kulla-dev@openjdk.java.net
  • Panama Project: panama-dev@openjdk.java.net
  • Valhalla Project: valhalla-dev@openjdk.java.net
• Security: security-dev@openjdk.java.net

Directory to area mapping

• make – Build team
• hotspot – HotSpot
  • cpu – Compiler, Runtime
  • jdk.* – Compiler
  • os – Runtime
  • os_cpu – Compiler
  • share
    • adlc – Compiler
    • aot – Compiler
    • asm – Runtime
    • c1 – Compiler
    • ci – Compiler
    • classfile – Runtime
    • code – Compiler
    • compiler – Compiler
    • gc – GC
    • include – HotSpot
    • interpreter – Runtime
    • jfr – JFR
    • jvmci – Compiler
    • libadt – Compiler
    • logging – Runtime
    • memory – Runtime, GC
    • metaprogramming – Runtime
    • oops – Runtime
    • opto – Compiler
    • precompiled – Runtime
    • prims – Runtime, Serviceability
    • runtime – Runtime
    • services – Runtime
    • shark – Compiler
    • trace – Runtime
    • utilities – Runtime
• java.base
  • Core Libs should almost always be included but LangTools, HotSpot, Security and/or I18n may also be involved.
  • classes
    • crypto – Security
    • internal – HotSpot, Core Libs
    • invoke – Core Libs
    • io – NIO
    • lang – Core Libs
    • launcher – LangTools
    • math – Core Libs
    • net – Net
    • nio – NIO
    • reflect – Core Libs
    • security – Security
    • text – I18n
    • time – Core Libs
    • util – I18n, Core Libs
  • conf
    • sdp – Net
    • security – Security
  • legal –
  • lib/security – Security
  • man
    • java.1 - LangTools
    • jfr.1 - Runtime
    • keytool.1 - Security
  • native
    • common –
    • include – Runtime, Core Libs
    • jspawnhelper – LangTools
    • launcher – LangTools
    • libfdlibm – Core Libs
    • libjava – Core Libs
    • libjimage – LangTools, Core Libs
    • libjli – LangTools
    • libjsig – HotSpot
    • libnet – Net
    • libnio – NIO
    • libosxsecurity – Security
    • libverify – LangTools
    • libzip – Core Libs
• java.compiler – LangTools
• java.datatransfer – AWT
• java.desktop – Client
  • Many files in the awt directories are shared between 2D and AWT
    • See https://openjdk.java.net/groups/2d/2dawtfiles.html
    • And see https://openjdk.java.net/groups/2d
  • color, font, freetype, geom, imageio, java2d, jpeg, lcms, mlib, print, Graphics primitives – 2D
  • splashscreen, dnd, eawt, lwawt – AWT
  • im, InputMethods – I18n, AWT
  • libjsound, sound – Sound
  • accessibility, laf – Swing
• java.instrument – Serviceability
• java.logging – Core Libs
• java.management – Serviceability
• java.management.rmi – Serviceability
• java.naming – Core Libs
• java.net.http – Net
• java.prefs – Core Libs
• java.rmi – Core Libs
• java.scripting – LangTools
• java.se – Core Libs
• java.security.jgss – Security
• java.security.sasl – Security
• java.smartcardio – Security
• java.sql – Core Libs
• java.sql.rowset – Core Libs
• java.transaction.xa – Core Libs
• java.xml – Core Libs
• java.xml.crypto – Security
• jdk.accessibility – Swing
• jdk.aot – HotSpot Compiler
• jdk.attach – Serviceability
• jdk.charsets – I18n, Core Libs
• jdk.compiler – LangTools
• jdk.crypto.cryptoki – Security
• jdk.crypto.ec – Security
• jdk.crypto.mscapi – Security
• jdk.crypto.ucrypto – Security
• jdk.dynalink – LangTools
• jdk.editpad – LangTools
• jdk.hotspot.agent – Serviceability
• jdk.httpserver – Net
• jdk.incubator.foreign – LangTools
• jdk.incubator.httpclient – Net
• jdk.incubator.jpackage –
• jdk.internal.ed – LangTools
• jdk.internal.jvmstat – Serviceability
• jdk.internal.le – LangTools
• jdk.internal.opt – LangTools
• jdk.internal.vm.ci – HotSpot Compiler
• jdk.internal.vm.compiler – HotSpot Compiler
• jdk.internal.vm.compiler.management – HotSpot Compiler
• jdk.jartool – LangTools
• jdk.javadoc – LangTools
• jdk.jcmd – Serviceability
• jdk.jconsole – Serviceability
• jdk.jdeps – Core Libs
• jdk.jdi – Serviceability
• jdk.jdwp.agent – Serviceability
• jdk.jfr – JFR
• jdk.jlink – LangTools
• jdk.jshell – LangTools
• jdk.jsobject – LangTools
• jdk.jstatd – Serviceability
• jdk.localedata – I18n
• jdk.management – Serviceability
• jdk.management.agent – Serviceability
• jdk.management.jfr – Runtime
• jdk.naming.dns – Core Libs
• jdk.naming.rmi – Core Libs
• jdk.net – Net
• jdk.nio.mapmode – NIO
• jdk.pack – LangTools
• jdk.rmic – Core Libs
• jdk.scripting.nashorn – LangTools
• jdk.scripting.nashorn.shell – LangTools
• jdk.sctp – Net
• jdk.security.auth – Security
• jdk.security.jgss – Security
• jdk.unsupported – Core Libs
• jdk.unsupported.desktop – Swing
• jdk.xml.dom – Core Libs
• jdk.zipfs – Core Libs
• sample –
• utils –

About this Guide

This guide is being maintained through the OpenJDK Developers’ Guide Project. The source repository is available at GitHub. The revision hash at the bottom of each page refers to the latest change that modified that particular page.

Comments and questions may be sent to guide-dev (at) openjdk.java.net. Please let us know if there’s anything in the guide that isn’t clear.

Glossary

accepted (by the CCC)

The stage of the CCC process after “DRAFT”, and “PROPOSED”. At this stage the primary goals are to ensure that the proposed changes are suitable for the release in a general sense and that the requisite JCK and SQE resources will be available.

approved (by the CCC)

The stage of the CCC process after “FINAL”. The CCC has approved the final version of the request which permits push into the project forest.

changeset

A collection of changes with respect to the current clone of a repository.

development freeze

The date by which all planned work should be complete for a particular line of development. After a line’s development freeze, only exit-criteria bugs may be fixed in that line.

forest

A collection of Mercurial repositories which can be managed as a set of nested repositories. The name “Forest” originally came from the Mercurial “Forest Extension” which can be used with some versions of Mercurial, but in general is no longer recommended. The script common/bin/hgforest.sh can be used to apply a Mercurial hg command to all the repositories in a forest.

Group

A collection of Participants who engage in open conversation about a common interest. That interest may be in the creation, enhancement, or maintenance of a specific body of code or it may lie in other areas, e.g., quality, documentation, or evangelism. See the Group overview.

Mercurial

A free, cross-platform, distributed source management tool. Source bundles and binary packages for Mercurial are available at https://www.selenic.com/mercurial/wiki/index.cgi. The main Mercurial documentation is available at http://hgbook.red-bean.com.

Project

A collaborative effort to produce a specific artifact, which may be a body of code, or documentation, or some other material. See the Project overview.

repository

A directory tree in the filesystem that Mercurial treats specially. This tree contains the source files and their revision history.

trivial

A change that is small, well contained, and that makes no semantic changes. Typical examples are fixing obvious typos or renaming a local identifier. A trivial change can also be pushing an already-reviewed change that was missed in an earlier push (e.g., forgot to add a file) or generated changes like a git revert. It’s up to the author of a change to claim that the change is trivial in the RFR, and it’s up to the Reviewer whether to approve such a claim. A change is trivial only if the Reviewer agrees that it is. A trivial change doesn’t need to wait 24 hours before being pushed, and it only needs one Reviewer, even in areas where stricter rules for pushing normally apply.

webrev

A tool and its output. In JDK release forests, the script, webrev.ksh, examines a forest or repository to generate a set of web-based views of differences.