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.


Quick Links

OpenJDK consists of a number of Groups. Members of a group collaborate on an area of mutual interest. The right hand side bar on the OpenJDK website has a list of all groups in OpenJDK. If you’re interested in a specific area, this is where you would start your OpenJDK experience. Look at the group’s information and wiki pages, and see what projects they sponsor on the Census page. The Census shows the structure of the OpenJDK Community.

Projects are where the coding and much of the other work is done in OpenJDK. There are many different projects, some produce shippable artifacts, like the JDK Project, some produce tools to be used by developers of these artifacts, like the Code Tools Project or Project Skara, and some produce documentation, like the Developers’ Guide Project. Many projects designs and develops new features for the Java language or the JVM, but there are also less code centric projects like the Duke Project which collects images of the Java mascot, Duke.

Author, Committer, Reviewer

OpenJDK has a few different roles that determine who has the right to do what in the different projects. These roles are defined in the OpenJDK Bylaws. The roles are earned based on experience and knowledge within each project.

A Contributor can have different roles in different projects. When you’re new to a project you don’t yet have a formal role in that specific project, even though you might have earned roles in other OpenJDK projects or have been recognized as a Contributor or a Member of OpenJDK. By contributing high-quality content you’ll soon be eligible for OpenJDK roles in the project. First Author, then Committer, and finally Reviewer if you stay active and earn the trust of the community. Trust is an important part of earning these roles. There’s a rough guideline saying that to become a Committer you should have contributed 8 significant changes, and to become a Reviewer you should have contributed 32 significant changes. In reality it’s not as easy as “just” contributing code. You need to build a track record of good decisions and sound judgment and show that you know what differentiates a good change from a not so good one. It’s not only correctness of the code that matters, it’s also the appropriateness. In the end the trust you’ve earned is put to the test through a vote.

Becoming an Author

Becoming an Author is the first step. To achieve this you need to contribute two changes to the project in which you wish to become an Author. Once your changes are pushed into the code base and has been vetted enough to determine that the changes were indeed good changes you can go ahead and send an email to the project lead of that particular project and ask to be added as an Author. The OpenJDK Project description has a template for such an email. In response to your email you will get a time-limited invite which you should fill out.

To see who the project lead is for your project, see the OpenJDK Census. The Census unfortunately doesn’t provide email addresses for people, but assuming you have been active on the project mailing list (since you are applying for Author after all), you should be able to find the lead’s email address in your local email archive, or ask your sponsor.

As an Author you will get your OpenJDK user name. This should be associated with your GitHub account in order for the bots to be able to identify you on GitHub. See the Skara documentation for more details on that. Once that’s done you can create PRs and get them reviewed, but you will still need a sponsor to approve your change before it can be integrated. You’ll also get write access to JBS and the OpenJDK wiki related to the project in question, and to via an SSH key provided at the time you accept your invitation.

Becoming a Committer

To become a Committer you should show that you can produce non-trivial changes that are accepted for inclusion into the project code base. The number eight has been seen as a formal lower limit on the number of changes, but since the changes must be non-trivial, or “significant” as the OpenJDK Project description says, and the definition of significant is subjective, the general recommendation is to wait with a Committer nomination until there’s at least 10-12 changes pushed to have some margin for different interpretations of “significant”. It’s always a good idea to seek the advice of a sponsor who can guide you through the process to becoming a Committer - you will need one later to run the Committer vote anyway. They probably will have a better idea of what constitutes a “significant” change.

Once you have the required changes, a Committer in the project can start a vote by sending an email proposing that you should become a Committer. The email should follow the template found in the OpenJDK Project description.

A Committer is allowed to push changes without the aid of a sponsor. A Committer is also allowed to nominate other non-Committers to become Committers in the project.

Becoming a Reviewer

To become a Reviewer you must show a track record of sound and correct judgment calls as mentioned above. Being a good Committer doesn’t necessarily make you a good Reviewer. As a Reviewer you have the power to approve changes for inclusion into the project source code. This means that a Reviewer needs to be able to judge the quality and appropriateness of any proposed change, not just the mechanics of the code.

The assumption is that after having produced 32 significant changes one should have become familiar with the process around reviews and the requirements around getting a change approved. This should really be seen as a minimum requirement though. A more practical consideration would be to look at whether the non-trivial commits of a potential Reviewer are accepted largely intact or whether they are always being refined by the review process. There may be cases where it will take significantly more than 32 changes for a Committer to be ready to become a Reviewer.

Once you are deemed ready, a Reviewer in the project can start a vote by sending an email proposing that you should become a Reviewer. The email should follow the template found in the OpenJDK Project description.

Non-trivial/Significant changes

One key definition when advancing through the OpenJDK roles is the significant change. What exactly does it take for a change to be significant?

Instead of describing the significant change (because that’s quite difficult to define) provided here is a few examples of changes that wouldn’t be considered significant or for other reasons wouldn’t count as significant contributions.

To the top

Contributing to an OpenJDK Project

Contributing to OpenJDK can take many forms. Writing code and providing patches is just one of them. A big part of developing a feature or a bugfix is testing and code review. Anything you can do to help out in these areas will be recognized as a contribution. Join the mailing lists to engage in design discussions and reviews, and download the latest EA builds or project repositories to try out new features and give feedback. If you see some misbehavior, or if you see somebody mention some misbehavior on some internet forum, try to track it down. Good bug reports with reproducible test cases are extremely valuable and make excellent contributions.

Anything you can do to spread the word about Java, new features, and your experiences using the JDK will be helpful for the community and to the OpenJDK developers. Trying out a new feature and reporting your experiences is also a contribution. Whether you find that the new feature improves your application, or if you find some area that needs to be improved, your feedback is valuable to the developers of that feature.

If you have a success story where Java solved your problem, or if you successfully upgraded to a more recent version of the JDK and noticed some improvements, spreading this story through a blog, news article, or some other channel is also a contribution.

If you’re in a position to choose what programming language to use in a project, in a tutorial, or in a class, you have the power to enlarge the Java community in a very direct way, and your colleagues or students will get an opportunity to learn one of the most used programming languages in the world.

I have a patch, what do I do?

Quick Links

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 OpenJDK. 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. An alphabetical list of all of the assigned OpenJDK usernames may be found on the OpenJDK people list.

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 (see Becoming an Author). For your first changes, ask your sponsor to help you create the issue or file the bug through the Bug Report Tool.

5. Get acquainted with local process

Even though we strive to unify how things are done within OpenJDK, different areas and projects in 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 OpenJDK.

Why is my change rejected?

Quick Links

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.

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.

To the top

Mailing Lists

Quick Links

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:

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 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.

Technical discussions around the implementation of the project artifacts. This is also where code reviews happen.
Technical discussions around the usage of the project artifacts.
General discussions around the project. The special case discuss(at) is used for general discussions around OpenJDK. Discussions around new project proposals usually happens here.
Changeset notifications from the source code repositories maintained by the project.
General project announcements. These lists are tightly moderated and are expected to be low traffic. The special case announce(at) is used for announcements for OpenJDK.
Expert group discussions. The list is restricted; only members of the expert group can subscribe.
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.
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

To the top

Code Conventions

Quick Links

To the top

JBS - JDK Bug System

Quick Links

JBS is a public issue tracker used by many OpenJDK projects. It’s open for anyone to read and search. In order to get write access you need to be registered in the OpenJDK Census, for instance by becoming an Author in an OpenJDK Project.

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 OpenJDK you can either use the Bug Report Tool or, if you are registered in the OpenJDK Census, report the bug directly in JBS. Try to make the bug report as complete as possible to make it easier to triage and investigate the bug.

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

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

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 Labels

JBS labels are used to tag and group related issues. 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. Most areas have their commonly used labels to identify issues in their respective area. Make an effort to find and use these labels. 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.

JBS labels should not be used to write documentation - don’t try to write sentences using labels. Adding a number of random labels is unlikely to be helpful to anyone.

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.

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.

Label Description
(Area)-interest Used to indicate that an area (usually a team or project) is interested in the issue. This label doesn’t indicate ownership of the issue. E.g., redhat-interest, azul-interest, coin-interest
(Area)-related Used to indicate that an issue is related to a specific area (usually a feature or project). This label doesn’t indicate ownership of the issue. E.g., graal-related, testcolo-related, doc-related
(Rel)-bp Used to indicate that a bug would be suitable for backport to a release (Rel). This isn’t a decision to backport, just a suggestion / recommendation. E.g., 11-bp

Used in the rampdown phases of specific releases to request approval of changes that requires project lead approval (or similar) to be included. (Rel) is the release in question. E.g., jdk11-critical-request

(Rel)-critical-approved is used to signal that the change has been approved for inclusion. E.g., jdk11-critical-approved
(Rel)-critical-watch is used for issues that must get into a specific release but risk running late. The label is used while the issue is still in progress and is replaced with (Rel)-critical-request once the issue is resolved. E.g., jdk11-critical-watch

These labels are always placed on the main JBS issue (the bug), never on backports or subtasks.

Used to request deferral of changes that requires project lead approval (or similar) to defer. (Rel) is the release in question. E.g., jdk12-defer-request

(Rel)-defer-yes and (Rel)-defer-no are used to indicate wether the deferral has been approved or not. E.g., jdk12-defer-yes

These labels are always placed on the main JBS issue (the bug), never on backports or subtasks. Further details are found in the JDK Release Process.

Used in the rampdown phases to request the late inclusion of an enhancement. (Rel) is the release in question. E.g., jdk10-enhancement-request

(Rel)-enhancement-yes and (Rel)-enhancement-no are used to indicate the response on the request. E.g., jdk10-enhancement-yes, jdk10-enhancement-no


Used in rampdown phase 2 to indicate that an issue would be of interest to get integrated into release (Rel). E.g., jdk12u-fix-request

(Rel)-fix-SQE-ok is used to indicate that the issue will be covered by the test plan for (Rel). E.g., jdk12u-fix-SQE-ok
(Rel)-fix-yes and (Rel)-fix-no are used to indicate wether an issue has been approved for backport to (Rel). E.g., jdk12u-fix-yes

(Rel)-na Used to indicate that the issue doesn’t affect release (Rel) or later. Could for instance be a bug in code that was removed in (Rel).

Used to indicate that (Team) has triaged this issue for release (Rel). It’s encouraged that all open bugs are triaged on a regular basis so that old bugs aren’t forgotten. It’s therefore common to see several triage labels on the same issue which helps keeping track of which bugs has been triaged for each release. E.g., oracle-triage-13

There are many label variants that include the word triage in some form. The form described above is the only one recommended. Please refrain from using other forms.
aot Used to identify issues in Ahead of Time Compilation.
appcds Deprecated. Was used to identify issues in Application Class-Data Sharing. The cds label is now used instead.
c1 Used to identify issues in the C1 JIT compiler.

Used to identify issues in the C2 JIT compiler.

c2-.* labels are used to identify different c2 features. E.g., c2-intrinsic, c2-loopopts
cds Used to identify issues in Class Data Sharing.
cleanup The cleanup label is used to indicate enhancements which has no semantic changes, whose only purpose is to make the code more maintainable or better looking.
docker Used to identify issues in docker support.

Used to identify issues in specific garbage collectors in the JVM. E.g., gc-g1, gc-shenandoah, gc-serial, gc-epsilon

There are also labels in use to identify different GC features or areas rather than GC algorithms. E.g., gc-g1-fullgc, gc-largeheap, gc-performance
graal Used to indicate that this is a Graal issue. (Something that needs to be fixed in Graal rather than in OpenJDK.)
graal-integration Reserved for Graal integration umbrella bugs. The automated integration script will break if this label is used for other bugs.
hgupdate-sync Used to identify backport issues automatically created by HG Updater (a script that monitors the hg repositories for changes).
hs-nightly Deprecated. Was used to tag bugs found in the HotSpot nightly testing. Since we are now running tiered testing there is no more nightly HotSpot testing. See tier[1-8].
hs-sbr Used to identify issues that are found in the “same binary runs”, a stress testing method used to find intermittent failures.
hs-tier[1-8] Deprecated. Was used to identify which HotSpot tier a test failure was seen in. We don’t separate HotSpot tiers from the JDK tiers anymore. See tier[1-8].
i18n Used to identify issue in internationalization. i18n is short for internationalization meaning “i 18 letters and an n”.
integration-blocker Used to indicate that a bug is present in a downstream repository but not present in the upstream repository and is therefore blocking integration of downstream changes into upstream.

An intermittent issue is one that fails sometimes but not always. The exact reason for the intermittent failure is per definition unknown. Once the reason has been identified the issue is no more considered intermittent. An issue isn’t intermittent if some characteristics has been found that triggers the failure consistently, even if the actual cause for the failure hasn’t been found. For instance if a test fails every time it’s executed on a specific host but not on other hosts it wouldn’t be considered intermittent as it fails consistently on that specific host. In other cases it may be that we know that a test sometimes is unlucky in some respect and fails due to this. This test could still be considered intermittent even though we know what the reason is if the reason itself appears intermittently.

Some issues may seem intermittent when looking at test results, even though the reason for failing is actually known. One example is where a test fails consistently on a specific host, or due to specific conditions in the environment. These failures shouldn’t be considered intermittent but it may still be valuable to tag these in JBS with one of the labels intermittent-hardware or intermittent-environment. This will help to faster identify that the cause of the failure is known without having to read through the entire bug.

A test that should be platform agnostic but is consistently failing on a specific OS would for instance be labeled with intermittent-environment, while a test that fails every time it’s run on some specific hardware would be labeled with intermittent-hardware.

Used to tag bugs that for some reason is wasting time or in other ways are causing pain for the OpenJDK maintainers. Examples of issues that could be considered a pain:

  • A bug that occurs frequently in testing, maybe on a specific platform, maybe specific to one vendor’s test infrastructure, and requires that many maintainers investigate the failure in different test runs just to realize it’s the same issue as has been seen and reported before, or worse, don’t realize it’s a known issue and file a duplicate bug in JBS.

  • Bugs that cause tests to fail without a proper explanation causing several maintainers to investigate the failures just to realize there is no information to be found.

  • An underlying bug that causes several tests to fail intermittently.

  • A bug that causes a test failure in a faraway place and the failure isn’t acted on quickly.

There are other cases as well and there is some flexibility in the definition. If you see a problem that is causing pain for a large number of maintainers, add an explanation in the JBS issue to why you think the issue is a pain and add the label.

If you have a maintainer-pain bug assigned to you please consider fixing it asap. If you chose not to work on the issue, you should at least be aware that you are choosing to waste others’ time and people will be affected by this choice.

As with any issue the best way to deal with a maintainer-pain issue is to fix it. Another way to reduce the noise is to exclude the failing test. This is a viable option if there is a limited set of tests that are failing and the bug is actively investigated. When excluding a maintainer-pain issue, remember to move the maintainer-pain label to the JBS issue used to exclude. Leaving the label on the closed exclude-issue is helpful for tracking purposes.

The noreg-.* and nounit-.* labels are used to explain why a bugfix doesn’t need/have a regression test or a unit test. The suffix of the label is described below.

Change can be verified by running an existing SQE test suite; the bug should identify the suite and the specific test case(s).
Change can be verified by running the JCK; the bug should identify the specific test case(s).
Change can be verified by running an existing external test suite; the bug should identify the suite and the specific test case(s).
Change only affects documentation.
Change only affects demo code.
Change only affects build infrastructure (makefiles, copyrights, scripts, etc.).
Change is a fix to a regression or unit test itself.
Change is for a performance bug for which writing a regression test is infeasible; the bug should describe how to verify the fix.
It’s too hard to write a regression or unit test for this bug (e.g., theoretical race condition, complex setup, reboot required, editing of installed files required, specific graphics card required); the bug should explain why.
Testing requires a very long running time (e.g., more than a few minutes).
Testing requires an unreasonable quantity of resources (e.g., tens of gigabytes of filesystem space).
Change is so trivial that nothing could possibly go wrong with it.
Change is a cleanup or refactoring of existing code that is covered by existing tests.
Change only affects localized text.
Change is a reversion of a previous faulty change.
Regression or unit test is unnecessary or infeasible for some other reason; the bug report should explain why.
Examples: If a bug fix only corrects a change in the build system, then add the noreg-build label to the corresponding bug. If the change improves loop optimizations in HotSpot, then add nounit-perf to the corresponding bug.
performance Used to identify an issue with noticeable performance impact. Either positive or negative.
pit Deprecated. Was used to indicate that a failure happened in product integration testing (PIT). Since we are now running tiered testing there is no more PIT. See tier[1-8].
problemlist One or more tests has been problemlisted due to this bug.
regression Used to identify regressions. A regression is a bug that didn’t exist in the previous release. Ideally all regressions must be fixed in order to release the next major version.
release-note Used to indicate that the issue is a release note. See Release Notes.

Used to indicate whether a change requires a release note or not. The labels are always placed on the main JBS issue, never on the actual release note issue. See Release Notes.

release-note=done is deprecated and should no longer be used.
RN-.* Used to indicate what kind of change the release note is for. See Release Notes.
starter A starter bug is a well contained, small issue that is suitable for someone new to the codebase.
startup Used to identify an issue as affecting Java SE startup performance.

Used to identify TCK conformance stoppers (e.g. failure of a valid TCK test that exists in a shipped TCK). The release number indicates which release of the TCK that failed. E.g., tck-red-11

There are tck-red labels without the release number out there as well. This usage is deprecated.
The labels test, test-only, and testbug are deprecated and should no longer be used. Use noreg-self to indicate that an issue is a bug in test code.

Used to indicate which tier in the jdk/jdk CI pipeline a test failure has been seen in. Lower tiers would in general mean higher urgency to fix the issue. E.g., tier1, tier2

Please note that these labels are reserved for bugs seen in the jdk/jdk CI pipeline. Use (Rel)[-tier1] for other CI pipelines, where (Rel) is the name of the pipeline. E.g. 8u-tier1
vthreads Used to identify an issue in the virtual thread implementation.
webbug Used to identify a bug as submitted on
zgc Used to identify an issue in ZGC.

To the top

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?

    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?

    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.
  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?]

    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.

    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?

    It’s often sufficient to build and test on a single platform, but sometimes it’s not. Use discretion.
  8. Is modification of shared C code needed?

    Build and test on at least one instance of all three of the supported operating systems (Solaris, Linux, and Windows).
  9. Is modification of C or Java platform-specific code needed?

    Build and test on all relevant platforms. Code under src/solaris builds on Solaris, Linux, and MacOS X despite its name.
  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

    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.

To the top

Cloning the JDK

Quick Links

The complete source code for the JDK is hosted at GitHub. You can browse the code directly in the openjdk/jdk repository, or download the code for offline browsing, editing, and building using git clone.

$ git clone

openjdk/jdk is the mainline JDK development repository where the next major release of the JDK is being developed. Other projects have their own repositories on GitHub.

Note that source may be available from other locations, for example from a full JDK distribution. However, OpenJDK contributions must use source from the appropriate OpenJDK GitHub repository since other source distributions may contain older code or code which differs due to licensing. Consult the Project’s documentation or mailing list to determine the appropriate repository, development conventions, and helpful tools.

If you intend to contribute patches, you should first fork the repository on GitHub and clone your own personal fork as shown below. To fork a project on GitHub, go to the GitHub project page and click the ‘Fork’ button in the upper right corner, then follow the on screen instructions.

This is the typical development model:

Diagram of upstream repos and user's clone

Pushes to your personal fork can be made either using HTTPS or SSH. These examples assume you have an SSH key installed on GitHub. If this is the first time you clone your personal fork of an OpenJDK repository you may want to create an SSH key to use with it. See Generating an SSH key below. Once you have your personal fork and an SSH key to go with it, go ahead and clone.

$ git clone
$ cd jdk
$ git remote add upstream

In the example above Duke cloned his personal fork of the JDK mainline repository using SSH. You should of course use your own GitHub username instead. Then, by adding a new remote named ‘upstream’, the clone is associated with openjdk/jdk. Doing this will allow the tooling to automatically create a PR on openjdk/jdk whenever a change is pushed to the personal fork. The way that works is that once the change has been pushed to the personal fork, and you navigate to the openjdk/jdk repository on GitHub, there will be a message saying that you just pushed a change and asking if you want to create a PR.

The recommendation is to always create a new branch for any change you intend to implement. By doing that you can easily work on many different changes in parallel in the same code repository. Unless you know what you are doing, the recommendation is also to always base your new branch on the master branch.

$ git switch -c JDK-8272373 master

Here we create a new branch called JDK-8272373 based on the master branch and set the repository up to work in that new branch.

git switch was introduced in Git version 2.23. For earlier versions of Git git checkout can be used instead. However it is always recommended to use the latest versions of all your tools when possible.

More information about how to work with git and the dedicated tooling that is available for OpenJDK can be found in the Project Skara Documentation. If you’re new to git you can also read more about how to work with it in one of the many fine git tutorials available on the Internet. For instance the Pro Git book. This guide doesn’t aspire to become another git guide.

Generating an SSH key

For security reasons you should always create new keys and use different keys with each repository you clone. The ssh-keygen command generates an SSH key. The -t option determines which type of key to create. ed25519 is recommended. -C is used to add a comment in the key file, to help you remember which key it is. 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 ed25519 -C openjdk-jdk -f ~/.ssh/openjdk-jdk
Generating public/private ed25519 key pair.
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /Users/duke/.ssh/openjdk-jdk.
Your public key has been saved in /Users/duke/.ssh/
The key fingerprint is:
SHA256:WS4jCQMtat75ZEue+so+Lgj7V/sdMtj1FTNkfNsCfHA openjdk-jdk
The key's randomart image is:
+--[ED25519 256]--+
|  ..       ..oE  |
|  ...       o+o .|
| . .o     .  o+.o|
|..   o . +    .=.|
|o . . o S o   .. |
|.. o +.+ + . .   |
|o.  *.+.+ . .    |
|o....=.  + .     |
| .=B=. .. .      |

~/.ssh/openjdk-jdk is a text file containing your private ssh key. There’s a corresponding public key in ~/.ssh/ (as detailed in the example above). You should never share your private key. The public key on the other hand should be uploaded to GitHub. Follow the steps below to do that.

Now you are ready to clone your openjdk/jdk fork using SSH.

To the top

Building the JDK

Quick Links

The JDK build system is a fairly complex machine that has the ability to build anything from a single module to a complete shippable JDK bundle with various levels of debug capabilities, run tests, install your newly built JDK on your system, or cross-compile for some other system. The build uses make and a few other tools that you will have to install on your system before starting.

The JDK supports incremental builds. This means that if you have a complete build and make changes in just a single part of the JDK (e.g. a module or part of the JVM), only that particular part needs to be rebuilt. So subsequent builds will be faster and you can always use a make target that results in a complete JDK image without having to worry about actually building the entire JDK every time. Please note that the incremental build do have limits in its understanding of what you change. For instance, if you change behaviors or conventions in one module there may be other parts of the JDK that implicitly depends on these without make’s knowledge. For this reason you may have to rebuild several modules, or do a clean build if you change things that may have a wider impact.

The examples below show the steps taken to build the JDK source code. Please see Cloning the JDK for information on how to download it. These examples were written in the JDK 17 development time frame which is why the boot JDK used here is JDK 16. Note that the download links used here point to JDK 16 bundles. To build JDK N, use JDK N-1 as the boot JDK.

The configure script will tell you what additional packages you need. In this first example several packages were needed since this build was performed on a clean Ubuntu installation. The configure script was run several times to get all the dependencies, but only the commands actually needed to get the JDK built are included in the log. This is just an example log, don’t copy the apt-get install line. Instead run sh ./configure to see what packages you actually need on your system.

$ wget
$ tar xzf openjdk-16_linux-x64_bin.tar.gz
$ sudo apt-get install autoconf zip make gcc g++ libx11-dev libxext-dev libxrender-dev libxrandr-dev libxtst-dev libxt-dev libcups2-dev libfontconfig1-dev libasound2-dev
$ cd jdk
$ sh ./configure --with-boot-jdk=$HOME/jdk-16/
$ make images

The built JDK can be found in build/linux-x86_64-server-release/jdk. The exact path depends on your build platform and selected configuration.

The second example is from a clean (newly installed) Mac running MacOS Big Sur. Please note that in this case there are some steps taken outside of the terminal. First XCode and the XCode command line tools must be installed. It could be that the most recent version of XCode that you get from App Store is too new to have been properly tested with the JDK build. See the JDK build instructions for supported versions and more details in case you need to install an older version of XCode. In this example Mac Ports is used to install autoconf. autoconf can also be installed using Homebrew and surely through other sources as well.

$ curl --output openjdk-16.0.1_osx-x64_bin.tar.gz
$ tar xzf openjdk-16.0.1_osx-x64_bin.tar.gz
$ sudo port install autoconf
$ sh ./configure --with-boot-jdk=$HOME/jdk-16.0.1.jdk/Contents/Home
$ make images

In this case the built JDK can be found in build/macosx-x86_64-server-release/jdk.

Configuration options

The JDK build is extremely configurable. This list only contains the most basic configure options needed to get you started. Use configure --help to see a complete list of options.

Option What it does
--with-boot-jdk Tell configure what boot JDK to use to build the Java libraries.
--with-debug-level Set the debug level. Available levels are release, fastdebug, slowdebug, optimized.

Working with multiple configurations

Through the configure flags you will select what configuration of the JDK to build. The name of the output directory for the build depends on this configuration. In the example above the JDK ended up in linux-x86_64-server-release. This means that we made a release build of a 64 bit linux x86 version of the server JDK. If we change some of these options the output directory will be affected accordingly.

--with-debug-level is one example of a configure option that will change the output directory name. Sometimes it makes sense to have several different configurations in parallel. For example while debugging some code you might want to have both a debug build and a release build to be able to test it properly. The directory naming scheme makes this very easy. Simply configure and build the JDKs you need and they will end up next to each other in the build directory.

In the example above we built a release image. To build a debug image as well we can configure with --with-debug-level=slowdebug. This will give us a JDK where for instance asserts in the JDK source code are enabled. To select which JDK to work with in later calls to make add CONF=<configuration>.

$ sh ./configure --with-boot-jdk=$HOME/jdk-16/ --with-debug-level=slowdebug
$ make CONF=slowdebug images
$ ls build/

Make targets

make images, as used in the example above, will build a JDK image which is very close to what you’d get from any JDK provider. There are several other make targets you can use depending on what you’re looking for. The table below contains some commonly used make targets.

Target What it does
exploded-image This is the default make target that you’ll get if you simply invoke make.
image Builds a complete JDK image. A good target to use if you want to build a JDK for general usage or if you want to test something closer to the shipping product. This can also be a good target to use if doing something which might have a build aspect to it.
<name>-image Build just the image for any of jdk, test, docs, symbols, etc.
reconfigure Re-runs the configure script with the same arguments as given the last time.
demos Builds the demos which for instance make it easy to test something UI related.
docs Builds the javadoc. Note that a number of classes in the javadoc API are generated during the build, so make docs might do more than simply invoke javadoc, depending on the state of your build.
java.base Builds the base module. You can (re)build any module with make <module>.
hotspot Builds the JVM. Note that the JVM depends on several other parts of the JDK, so make hotspot might build more than just the JVM, depending on the state of your build.
clean Removes all files generated by make, but not those generated by configure. Useful when doing significant renaming or refactoring which may confuse the incremental build. To clean out a specific module only use make clean-<module>.
dist-clean Removes all files, including configuration.

There are many other targets available as well. Use make help to find out more.

To the top

Testing the JDK

Quick Links

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/

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 sense 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:

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


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 {
        var result = X.y();
        if (result != expected_result) {
            throw new RuntimeException("X.y() gave " + result + ", expected " + 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 != ”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


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);
    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.

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/

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.


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

foo/bar/                        4711   windows-all

In this example, 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/                        4710   generic-all
foo/bar/                        4711   windows-all

This would lead to being ProblemListed only on windows-all. The proper way to write this is:

foo/bar/                        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.

Remember to always add a problemlist label in the JBS issue referenced in the ProblemList entry.

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/

/* @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/          4720  generic-all
foo/bar/   4721  generic-all
foo/bar/          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.


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, 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.

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.

GitHub Actions

GitHub has a feature called GitHub Actions (GHA) that can be used to automate testing. The GHA is executed whenever a push is made to a branch in your repository. The bots will show the results of the GHA in your PR when you create or update it. The GHA in the JDK project is configured to run a set of tests that is commonly known as tier 1. This is a relatively fast, small set of tests that tries to verify that your change didn’t break the JDK completely. In tier 1 the JDK is built on a small set of platforms including (but not necessarily limited to) Linux, Windows, and MacOS, and a few tests are executed using these builds.

In addition to the testing you run manually before publishing your changes, it’s recommended that you take advantage of this automated testing that the GHA offers. This will for instance allow you to run tests on platforms that you may not otherwise have access to. To enable this on your personal fork of the JDK on GitHub go to the “Actions” tab and click the big green button saying “I understand my workflows, go ahead and enable them”. If you don’t understand these workflows there’s a link to the actual file that describes them right below the green button.

In case of failures in the GHA it’s always a good start to try to reproduce the failure locally on a machine where you have better control and easier access to a debug environment. There have been cases where the GHA has failed due to issues unrelated to the change being tested, e.g. because the GHA environment was updated and changes were needed to the JDK GHA configuration. The configuration is in general updated fairly quickly, so in cases were you can’t reproduce the failure locally, consider re-running the GHA later.

Please keep in mind that the tier 1 tests run by the GHA should only be seen as a smoke test that finds the most critical breakages, like build errors or if the JDK is DOA. These tests can never replace the targeted testing that you always must do on your changes. There are several areas of the JDK that aren’t part of tier 1 at all. To see exactly what tier 1 includes, please see the various TEST.groups files that you will find in the subdirectories of jdk/test/.

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 git or 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 generated. In areas where two reviewers are normally required, only one additional Reviewer is required for a backout since the person who is performing the backout also will review the change.

How to work with JBS when a change is backed out

  1. Close the original (failed) 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 automatically 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 prefixed with [BACKOUT].
    • Alternative 2 - an investigation issue was 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].
      • Add a relates to link between (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 git when a change is backed out

To backout a change with git, use git revert. This will apply (commit) the anti-delta of the change.

$ git show aa371b4f02c2f809eb9cd3e52aa12b639bed1ef5
commit aa371b4f02c2f809eb9cd3e52aa12b639bed1ef5 (HEAD -> master)
Author: Jesper Wilhelmsson <>
Date:   Wed Jun 23 20:31:32 2021 +0200

    8272373: Make the JDK mine
    Reviewed-by: duke

diff --git a/ b/
index 399e7cc311f..4961acb2126 100644
--- a/
+++ b/
@@ -1,4 +1,4 @@
-# Welcome to the JDK!
+# Welcome to my modified JDK!

 For build instructions please see the
 [online documentation](,

$ git revert aa371b4f02c2f809eb9cd3e52aa12b639bed1ef5
[master d454489052d] 8280996: [BACKOUT] Make the JDK mine Reviewed-by: duke

$ git show d454489052dc6ff69a21ad9c8f56b67fdeb435ee
commit d454489052dc6ff69a21ad9c8f56b67fdeb435ee (HEAD -> master)
Author: Jesper Wilhelmsson <>
Date:   Wed Jun 23 20:32:08 2021 +0200

    8280996: [BACKOUT] Make the JDK mine
    Reviewed-by: duke

diff --git a/ b/
index 4961acb2126..399e7cc311f 100644
--- a/
+++ b/
@@ -1,4 +1,4 @@
-# Welcome to my modified JDK!
+# Welcome to the JDK!

 For build instructions please see the
 [online documentation](,

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 repository 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.

Backing out a backport

In rare cases it may be necessary to back out a backport from an update release without backing out the original fix in mainline. This will require a somewhat different procedure and will result in a small mess in JBS. It’s extremely important to add comments in all relevant issues explaining exactly what’s happened.

The steps to take in order to do this are described below. (M) used below refers to the main bug entry - the first fix that was later backported.

  1. Close the original (failed) JBS backport issue (O).
  2. If the intention is to fix the backport and submit it again, create a redo-issue (R) to track that the work still needs to be done.
    • Clone (M) and add the prefix [REDO BACKPORT] on the summary - the clone becomes the redo-issue (R).
    • Add a relates to link between (R) and (O).
    • Set Fix Version of (R) to the target release for the backport - either the exact release if known, or <N>-pool if it’s not critical which release the fixed backport goes into.
  3. Create a backout-issue (B):
    • Alternative 1 - the broken backport is identified directly.
      • Create a sub-task to (R) with the same summary, but prefixed with [BACKOUT BACKPORT].
    • Alternative 2 - an investigation issue was created (I), and during the investigation backing out the backport is identified as the best solution.
      • Use the investigation issue (I) for the backout.
      • Change summary of (I) to the same as (M) and prefix with [BACKOUT BACKPORT].
    • Alternative 3 - no redo issue was created.
      • Create a backout-issue (B) with the same summary as (M) and prefix with [BACKOUT BACKPORT].
      • Add a relates to link between (B) and (M).
  4. Add comments to (M), (R) and (O) explaining the situation.

The end result in JBS should look like this:

JBS structure after backout and redo of a backport

For this example in JBS see the 15.0.2 backport of JDK-8272373.

Rationale for using this model

The approach described here has both advantages and disadvantages. The key invariants that lead to this model are:

Disadvantages of this model are that the list of backports in JBS will still list the old (failed) backport as the 15.0.2 backport, and the new backport will not be linked to using a backported by link. It is assumed that the advantages above outweighs the disadvantages and that the capital letter prefixes for the backout and the redo will be visible enough in JBS to alert that something fishy is going on.

To the top

Working With Pull Requests

Quick Links

Once you have made a change that you want to integrate into an OpenJDK code base you need to create a Pull Request (PR) on GitHub. This guide assumes that you have previous experience from using git and GitHub and won’t go into details of how those work. Still, the aim is of course to provide a useful guide, so send an email if more details are needed.

Rebase before creating the PR

It’s likely that other people have pushed changes to the code base since you created your branch. Make sure to pull the latest changes and rebase your fix on top of that before creating your PR. This is a courtesy issue. Your reviewers shouldn’t have to read your patch on top of old code that has since changed. This is hopefully obvious in cases where the upstream code has gone through cleanups or refactorings, and your patch may need similar cleanups in order to even compile. But even in cases where only smaller changes have been done, the reviewers shouldn’t have to react to issues like “that line of code was moved last week, why is it back there?”.

git rebase master

After the PR has been published, rebasing, force-pushing, and similar actions are strongly discouraged. Such actions will disrupt the workflow for reviewers who fetch the PR branch. Pushing new changes is fine (and even merging if necessary) for a PR under review. Incremental diffs and other tools will help your reviewers see what you have changed. In the end, all commits will be squashed into a single commit automatically, so there’re actually no drawbacks whatsoever to making commits to a PR branch during review.

Final check before creating the PR

Creating the PR is essentially the same as asking a large group of people to start reviewing your change. Before doing that, you want to make sure your change is done in every detail you have the power to control. These are a few of the things you should think about in order to avoid wasting people’s time on an unfinished change. (You may think that some of these are too obvious to even mention, but all of them are things that in the past have caused actual failures that broke the JDK for all developers out there.)

If you are unsure of any of these things but still want to go ahead and create the PR, don’t!

If you have an actual reason to create a PR before the change is all done, make sure to create it in DRAFT mode. The bot won’t add the rfr label or send emails as long as the PR is in DRAFT mode.

Life of a PR

  1. Make sure the PR is reviewable

    There are changes that span across several areas, for example wide spread cleanups or the introduction of a new langauge feature. Accordingly, the number of lines of code touched can be quite large, which makes it harder to review the entire PR. In such cases, it may make sense to split the change into several PRs, most commonly by grouping them by module or area.

  2. Set a correctly formatted title

    The title of the PR should be of the form “nnnnnnn: Title of JBS issue” where nnnnnnn is the JBS issue id of the main JBS issue that is being fixed, and the Title of JBS issue is the exact title of the issue as written in JBS. In fact, the title can be set to only the JBS issue id (nnnnnnn) in which case the bot will fetch the title from JBS automatically. If you are creating a backport PR, see Using the Skara tooling to help with backports for more details on the title requirements.

  3. Write a useful description

    The description of the PR should state what problem is being solved and shortly describe how it’s solved. Reviewers and other interested readers are referred to the text in the JBS issue for details, but the description should be enough to give an overview. This assumes there’s useful information in the JBS issue, like an evaluation etc. If not, add it.

    Remember that the description is included in many emails sent to lists with many receivers, so a too long description can cause a lot of noise, while of course a too short description won’t give the reader enough information to perform the review. If you have a lot of information you wish to add to your PR, like performance evaluations, you can put that in a separate comment in the PR.

  4. Finish the change before publishing it

    Each update to a published PR will result in emails being sent to all relevant lists. This is per design and it’s how we want it to be, but it also mean that if you publish a PR before you have gone through the final check mentioned above, and later find that a few more updates are necessary, a lot of people will get a lot of emails.

  5. Make sure all relevant groups are included

    The bot will make an attempt to include the groups that need to review your change based on the location of the source code you have changed. There may be aspects of your change that are relevant to other groups as well, and the mapping from source to groups isn’t always perfect, so make sure all relevant groups have been included, and add new labels using /label if needed.

  6. Allow enough time for review

    In general all PRs should be open for at least 24 hours to allow for reviewers in all time zones to get a chance to see it. It may actually happen that even 24 hours isn’t enough. Take into account weekends, holidays, and vacation times throughout the world and you’ll realize that a change that requires more than just a trivial review may have to be open for a while. In some areas trivial changes are allowed to be pushed without the 24 hour delay. Ask your reviewers if you think this applies to your change.

    At least one reviewer should be knowledgeable in the area being changed. Some areas (e.g. client and hotspot) require two reviewers in most cases, so be sure to read the relevant OpenJDK group pages for advice or ask your sponsor.

  7. Updating the PR

    You may need to change the code in response to review comments. To do this, simply commit new changes and push them onto the PR branch. The PR will be updated automatically. Multiple commits to the branch will be squashed into a single commit when the PR is eventually integrated.

    If the set of files in the PR has changed, this may affect the groups that need to review the PR. Make sure to adjust the PR labels accordingly.

  8. Merge the latest changes

    If your PR is out for review for a longer time it’s a good habit to pull from the target repository regularly to keep the change up to date. This will make it easier to review the change and it will help you find issues caused by other changes sooner. Typically this involves fetching changes from the master branch of the main JDK repo, merging them into your local branch, resolving conflicts if necessary, and then pushing these changes to the PR branch. Pushing additional commits and merges into the PR branch is fine; they will be squashed into a single commit when the PR is integrated. Avoid rebasing changes, and prefer merging instead.

    If there are upstream changes that might affect your change, it’s likely a good idea to rerun relevant testing as well. The GHA testing that’s done automatically by GitHub should only be seen as a smoke test that finds the most severe problems with your change. It’s highly unlikely that it will test your actual change in any greater detail - or even at all execute the code that you have changed in most cases.

  9. Integrate your change

    When you have the required reviews and have made sure all relevant areas have had a chance to look at your change, integrate by entering the command /integrate in a comment on the PR. If you are not yet a Committer in the project, ask your sponsor to enter the command /sponsor in the PR as well in order for your change to be allowed to be integrated.


Quick Links

As all OpenJDK projects are hosted on GitHub, most code reviews takes place there. When you publish a PR to an OpenJDK repository the corresponding JBS issue will get a link to the code review in the PR, making this the natural place to go for review. OpenJDK do however provide other tools and infrastructure for code reviews as well: The webrevs.

Webrev refers to both the tool used to create them and its output. The script, webrev.ksh, is maintained in the Code Tools project. Please note that this version of webrev is for use with mercurial and won’t work with the git based repositories. You don’t actually need tools like this anymore unless you want to host code reviews in other locations than GitHub.

On the GitHub reviews you will find links to webrevs. These are automatically generated by the bot and are provided as a complement for those who prefer this style of code review. Many OpenJDK developers are used to the webrevs as this was the default way to provide code for review before OpenJDK moved to GitHub. Though webrevs are mainly deprecated today, they used to be a central part of OpenJDK development and you may still see people use the word as a synonym for code review, so they do deserve to be mentioned here as well.

File storage for OpenJDK artifacts -

The server provides storage and display of code review materials such as webrevs and other artifacts related to the OpenJDK Community. This area can also be used to store design documents and other documentation related OpenJDK but not related to any specific project that have an OpenJDK wiki space for such purposes.

Any OpenJDK Author can publish materials on the server. Users can upload files to temporary storage using secure methods (rsync, scp, and sftp).

This site is for open source materials related to the OpenJDK Community only. Users uploading inappropriate materials will lose access and the material will be deleted. Please review the Terms of Use before using this server.

To the top


Quick Links

Development of the latest version of the JDK often results in bug fixes that might be interesting to include in some of the JDK update releases still being maintained. Moving a fix from a more recent release train (e.g. JDK 17) to an older release train (e.g. JDK 11) is called backporting.

The guideline for what to backport into a specific update release will vary over the lifetime of that release. Initially more fixes are expected to be backported as new features and large changes introduced in a mainline release stabilize. Over time the focus will shift from stabilization to keeping it stable - the release will go into maintenance mode. This means that bug fixes that require larger disruptive changes are more likely to be made in mainline and backported to more recent release trains only, and not to older release trains.

Over time it’s likely that the code base will diverge between mainline and any given update release, and the cost of backporting will increase. The cost in this case is not only the effort needed to perform the actual backport, but also the cost inferred by bugs introduced by the backport. This should be taken into consideration when deciding if a change should be backported or not. For more details on how to reason around what to backport, this email from JDK 8 Updates Project lead Andrew Haley has some guidelines for JDK 8u. The reasoning in this mail is specific to JDK 8u, but will in general apply to any JDK release in maintenance mode.

Any change that originally required a CSR will require a new CSR to be backported unless the backport was covered by the initial CSR. Changes to Java SE specifications cannot be made in an update release without a Java SE Maintenance Release. CSR-related issues affect interfaces and behavior and must be very carefully scrutinized.

Working with backports in JBS


Main issue - The top issue in a backport hierarchy. Eg. JDK-8272373 is a main issue, while JDK-8277498 and JDK-8277499 are backport issues of this main issue.

Example of backport hierarchy

In general there’s no need to create backport issues in JBS manually. All work that’s done in JBS in preparation for a backport (requesting approvals etc) is done in the main issue. The backport issue will be created automatically by the bots when you integrate the change to the source code repository.

There can be cases where it’s desirable to create a backport issue before the fix is done, e.g. if a CSR needs to be filed. In these cases set the Fix Version/s of the backport to N-pool, where N is the release train the backport is targeting. E.g. 17-pool. Please note that even if a backport issue is created ahead of time, all work done in JBS is still done in the main issue.

Obviously it’s possible to set the Fix Version/s to the exact release the backport is targeting, but this isn’t recommended. When a change is pushed, the bots will look at the main issue as indicated in the PR title, and look for backports with the current N.0.x release version as Fix Version/s, if no such backport is found they will look for N-pool, and if that isn’t found either, a new backport issue will be created. This means that if the backport has an exact Fix Version/s set, but is delayed and misses the release indicated by this Fix Version/s, a new backport issue is created with a small mess as the result.

Setting the Fix Version/s of a backport to N is always wrong. JDK N has already been released (or you wouldn’t be trying to backport to it) and can’t get any more fixes.

Requesting approvals for backports

In order to be allowed to push a change to one of the OpenJDK update development repositories (e.g. jdk17u-dev), an approval is required. The official process for how to request push approval for a backport describes in detail how to work with JBS when requesting approvals. In short, there’s a label jdk<release>u-fix-request that should be added to the main JBS issue. Also put a motivation as to why the issue needs to be backported as a comment in the main issue. Once the label and motivation has been added, wait for the maintainers of the release to approve your request. The approval will be indicated with a label, jdk<release>u-fix-yes, added to the main issue.

If the update release is in rampdown, changes are pushed to the release repository (e.g. jdk17u). During rampdown the bar to get changes in are significantly higher and fixes need to be approved with jdk<release>u-critical-request / jdk<release>u-critical-yes.

Using the Skara tooling to help with backports

The Skara tooling includes support for backports. The official Skara documentation describes in detail how to work with the tooling to create backport PRs on GitHub or using the CLI tools. As described in the documentation, the /backport command can be used on a commit (not a PR!) to create the backport PR. If a backport PR is manually created, set the PR title to Backport <original commit hash>. This ensures that the bots will recognize it as a backport as opposed to a main fix specifically targeting an older release. One can tell whether or not the bots recognized a PR as a backport by the backport label being added if it’s recognized.

To the top

How to fix an incorrect backport creation in JBS

If a main bug is targeted to a release and a fix referring to that main bug is pushed to a different release, then a backport bug is automatically created in JBS. 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’s 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). The same procedure can be used in the opposite situation, when a fix has been pushed to JDK N+1 when the JBS bug was targeted to JDK N, by switching N and N+1 below. Remember, to keep the record clean for the future, what matters the most is that the bug id used in the commit comment is the main bug, and that the “backports” (regardless of if they are to earlier or later releases) are Backport type issues of that main issue. Also make sure there are never more than one Backport issue targeted to any given 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 'na' and closed as 'Not An Issue' since JDK N+1 will automatically get this fix from JDK N later.
    • Change the Fix Version/s from ‘N’ to ‘na’.
    • Close the backport bug as “Not an Issue”.
  2. Clean up the main bug
    • Copy the push notification comment from the backport bug to the main bug, e.g.:
    Changeset: 12345678
    Author: Duke <>
    Date: 2020-10-23 15:37:46 +0000
    • 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 - or to an actual build number if the change has already made it to a promoted build (look in the backport bug if you are unsure). Pushes to ‘openjdk/jdk’ are fixed in build “master” and pushes to project repositories are fixed in build “team”.

Release Notes

Quick Links

Release notes for a product such as the JDK are part of the release deliverables providing a way to highlight information about a fix, such as when it may have changed behavior, or when it’s decided not to fix something. While what should go into a release note isn’t something that can be precisely defined, it should describe changes that are important for a user to take into account when they are upgrading to the specific version. While release notes should not duplicate information in other documents, they can serve to highlight that a change has been made.

Release notes are associated with a JBS issue that has been fixed (or in some cases not been fixed) in a release and are generated with each build of a release. Any note should be considered as an integral part of the fix process, rather than waiting until the end of the release to determine what to write. In OpenJDK, release notes are currently being generated for the JDK and JDK Updates projects.

Writing a release note

Writing the release note is the responsibility of the engineer who owns the issue. The note should be generated before the fix is reviewed, or in the case of known issues, when it’s determined that a fix won’t be possible in the release the issue was found in.

When writing a release note, be prepared for rather picky review comments about grammar, typos, and wording. This is for the sake of the Java community as a whole, as the language of the release note sets the tone for many blogs and news articles. For a widely used product like the JDK, the release notes are often copied verbatim (including typos) and published to highlight news in the release. This means that we need to take extra care to make sure the text in the release note is correct and follows a similar style.

The release note itself is written in a JBS sub-task of the issue that is used to push the change. There are a few steps to follow for the release note to find its way from JBS to the actual release note document.

  1. Create a sub-task (More → Create Sub-Task) for the issue that requires a release note - the main issue, that is, the JBS issue that is used to push the original change, not for backports or the CSR (if there is one).

  2. For the newly created sub-task, follow these steps:

    • The Summary should be a one sentence synopsis that is informative (and concise) enough to attract the attention of users, developers, and maintainers who might be impacted by the change. It should succinctly describe what has actually changed, not be the original bug title, nor describe the problem that was being solved. It should read well as a sub-section heading in a document.
    • Prefix the Summary with “Release Note:”.
    • Add the release-note label. This is required for the release note to be included in the release notes.
    • Add the proper RN-label if applicable to indicate what section of the release notes it should be included in (see RN-labels below).
    • Set the Assignee to the same person who owns the main issue.
    • Set Affects Version/s to the release versions for which the release note should be published.
    • Set the Fix Version/s to the same value that the main issue - in almost all cases this will be the version of mainline.
    • Enter the text of the release note in the Description field using markdown formatting, following the CommonMark specification. While the markdown won’t be rendered in JBS, you can use dingus to see what the release note will look like. Note that Github stlye ascii table formatting is supported but will not display correctly in the dingus page. For more information see General Conventions for Release Notes below.
    • While the Priority of the sub-task is set by default to be the same as the priority of the issue itself, it can be changed to adjust in what order the release note is listed compared to other release notes in the same build or release note section.
  3. Have the release note ready to be reviewed at the same time as the code is reviewed. If it’s later determined that a release note is necessary, then go back to the same engineers who reviewed the fix to review the release note. Special care should be taken when writing a release note that will cover changes related to a vulnerability fix in order to avoid describing technical details of how it could have been exploited.

  4. When you are done, Resolve the release note sub-task as Delivered. Only release notes where the sub-task has been resolved as Delivered is considered to be part of the EA/GA release notes. To avoid mixing up the release notes with the code fixes that have gone into a particular release or build, we don’t use Resolved/Fixed.

If you see an issue you feel should have a release note but you are not the assignee of the bug, then add the label release-note=yes to the main bug (not on a backport nor a sub-task). This acts as a flag to make sure that the release note is considered. This can be done even with fixes that have been shipped already if it’s noticed that there is confusion around the change. If, after discussion, it’s decided that a release note isn’t required either remove the label, or change it to release-note=no if it makes sense to have a clear indication that a release note isn’t required for the fix. The label release-note=yes can be removed once the release note sub-task has been created.

For examples of well written release note issues in JBS, see JDK-8276929 or JDK-8278458.

General Conventions for Release Notes

The following are general practices that should be followed when creating release notes.


Unless labeled otherwise it will be assumed that the release note documents a change in behavior (will have likely required a CSR) or other item which should be included in the release notes. If the note covers a more specific type of change, then one of the following labels can be included (notes of a similar type will be listed together).

A New Feature or enhancement in the release. The Summary must be the item/API or new functionality. The Description must contain the name of the new feature, its intended function, and how a user can utilize it. Example: JDK-8193026
A significant issue which has been fixed. This would normally be a regression or an issue which was unknowingly released in a new feature. The Summary must be a summary of the error that was fixed. The Description must contain a statement about what was fixed, how the fix effects the user, and any special conditions that a user should be aware of regarding the fix. Example: JDK-8184172
An issue that wasn’t possible to fix by the time the release was GA’d. The Summary must be a summary of the error that the user sees. The Description must contain details about the error, how it effects the user, and workarounds if any exist. Example: JDK-8191040
Only for major releases. The release note covers an API, feature, tool etc. which has been removed from the JDK. The Summary must be of the form “Removal of” Item/API. The Description must contain the list or name of the removed items/API with (optional) the reason for its removal. Include any special conditions that a user should be aware of regarding the removal. Example: JDK-8185066
Only for major releases. The release notes cover an API, feature, tool etc. that has been marked as deprecated in the release. The Summary must be of the form “Deprecated” Item/API. The Description must contain the name of the item that has been deprecated, the reason for its deprecation, and (optional) any special conditions that a user should be aware of regarding the possible future removal. Example: JDK-8179909
Used to indicate that the release note should be highlighted in some fashion, such as listing it at the beginning of the release notes.
Used to indicate that the release note is only relevant for a specific JDK distribution. E.g. RN-Oracle

Querying the Release Notes

The Release Notes for a particular release can be found using the JBS query

affectedversion = <version> and type = sub-task and labels = release-note

where <version> is the appropriate release value, e.g. 17.

HotSpot Development


Quick Links

While developing your fix, your might want your code to output some diagnostic information. You might even want to leave some logging in the code you check in, to facilitate future diagnostics.

The appropriate way to print logging output from HotSpot is through the Unified Logging Framework (JEP 158). It gives you a lot of nice features and enables common command-line options for all logging. Messages can also be “decorated” with e.g. uptime, level, tags. The JEP contains a thorough description of the feature, but a quick example might look like:

log_info(gc, marking)("Mark Stack Usage: " SIZE_FORMAT "M", _mark_stack_usage / M);

Where ‘gc’ and ‘marking’ are tags, and ‘info’ is the log level. This would be visible if the JVM were run with any of the following flags:


The API should be similar to:

log_<level>(Tag1[,...])(fmtstr, ...)

At the time of writing, the different log levels can be found in src/hotspot/share/logging/log.hpp.

To the top

Working With the Legacy Mercurial Servers

Quick Links

After the initial release of the JDK source code into OpenJDK in 2007 the OpenJDK project moved from TeamWare to using Mercurial. Starting in 2019 the source revision control has been moved to Git and GitHub. Even though most large projects have moved to Git by now, some still use the Mercurial servers. To access these projects some additional setup is required.

There used to be a sandbox repository that could be used for testing purposes. With the move to Git this has been replaced by GitHub Actions.

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

Installing and configuring Mercurial

Source bundles and binary packages for Mercurial are available at 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.

Once Mercurial is installed, create and edit the ~/.hgrc file to minimally contain the following entry:

username = <openjdk_username>

openjdk_username is in general the same as your GitHub user name. (See Contributing to an OpenJDK Project for more information.) If you don’t have a GitHub user name, you choose your OpenJDK user name when you sign the OCA. The user name should be 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.

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

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 for more information)
    Copyright (C) 2005-2014 Matt Mackall and others
  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

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

Cloning a Mercurial repository

Some Projects organized their code into multiple Mercurial repositories. For instance, JDK 8 uses a forest of multiple related repositories which contain components of the entire JDK. 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 jdk8u/jdk8u-dev forest into the directory 8u-dev.

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

    $ hg tclone 8u-dev
  2. To clone the forest using, first clone the main tree:

    $ hg clone 8u-dev
    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 8u-dev
    $ sh ./

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

$ ls
common              jaxp       make      test
configure           jaxws      Makefile  THIRD_PARTY_README
corba               jdk        nashorn       langtools  README

Cloning 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 jdk8u/jdk8u-dev into the default destination directory.

$ hg clone
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

Creating a Mercurial changeset

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/ 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/”.

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
$ 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, 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 of the change doesn’t have commit rights to the target repository and thus would not otherwise receive acknowledgment, or when there are multiple authors.

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


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

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 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
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 Mercurial changesets

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
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:


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

$ hg fetch
pulling from
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 Mercurial changesets

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.

Get your SSH key installed

First you should create a new SSH key. See Generating an SSH key for guidance on how to do that. Your public key (~/.ssh/ should be mailed as an attachment along with your JDK username to keys(at) 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 *
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.

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 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 jdk8u/jdk8u-dev repository.

default =
default-push = ssh://<JDK_username>

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

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}"
for i in ${hgdirs}; do
  d="`dirname ${i}`"
  echo "(cd ${d} && hg paths)"
  (cd ${d} && hg paths)
exit 0

Performing the push

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.

See Becoming a Committer for information about becoming a Project Committer.

To the top

The JDK Release Process

Quick Links

The JDK project has a well defined release process. JEP 3 describes this process in detail. This section intends to clarify some topics that often cause questions.

Release cycle

The release cycle starts when development of a new release begins, and ends when that release is delivered to the public. The current release cadence is six months. This means that every six months we start development of a new release, and every six months a new release is delivered. However, this doesn’t mean that each release cycle is six months. As described below, the total development time for a release (the release cycle) is actually nine months. Obviously this in turn doesn’t mean that all features are developed in nine months. Most features are developed for a much longer time than that, and goes through long time development in other project repositories, and through a series of preview and experimental stages. But any feature that is to be included in a specific release has a specific window of nine months to integrate the code into mainline and fix all the remaining bugs.

It may be tempting to integrate a new feature near the end of a release cycle, to get more time to fix all those last bugs before integration. Please don’t. If you are getting close to the end of a release and you still just have one more bug to fix, please defer your feature to the next release. It’s only six months out. Not only will this vouch for your new feature to be more stable on release, you will also help keeping the JDK as a whole more stable by allowing others to find and fix bugs in their new code that might come as a result of your changes.

Integrating early in a release is preferable, but all new features can’t be integrated at the same time. If many large changes enters the repository at the same time it will be more difficult to determine which change that caused all the new bugs. If you’re about to integrate a larger change you must therefore communicate this on the relevant mailing lists to synchronize with other projects that may also be planning to integrate something soon.

Milestones and phases

Throughout the release there are a number of milestones and phases that define where in the release cycle we are.

The start of a release
Since development is always ongoing in the mainline repository (openjdk/jdk), the start of a new release can be said to be when the former release is forked from mainline. After the start of the release follows six months of development to implement and integrate all the cool stuff that will go into the next release. After these six months ramp down begins.
Ramp Down Phase 1 (RDP1)
The ramp down of a release starts with a fork of the mainline repository. A clone of the entire code base is made and hosted in a separate ramp down repository (e.g. openjdk/jdk17). During the ramp down of a release we focus on bug fixing and stabilization in order to get the JDK ready for release. In RDP1 you may continue to fix P1-P3 product bugs (and some other issues) in the stabilization repo. For detailed information on what can be fixed when, see JEP 3. The start of RDP1 is essentially the deadline for integrating JEPs and enhancements into this particular release.
All Tests Run (ATR)
ATR is not a milestone described in JEP 3, but it’s still a concept that might be mentioned in discussions on this topic and is therefore good to know about. ATR (a.k.a. ATR Start) is the start of an approximately six week long test period where all tests in the test plan for the given release is ran. ATR usually starts at the same time as RDP1.
Ramp Down Phase 2 (RPD2)
In RDP2 the bar is higher to get changes into the release. For product bugs, only P1:s and P2:s are supposed to be fixed here, and to do so an approval is needed. See the Fix-Request Process for details on how to obtain one. All other product bugs should be deferred. Again, see JEP 3 for more details.
Release Candidate (RC)
Towards the end of the release cycle, when there are no more open product bugs targeted to the release, a stable build is selected to be the release candidate. This build will go through additional testing and if no more issues are found it will be the build released. If new bugs are found these are investigated and hopefully fixed, and a new build becomes the release candidate. The RC phase has a few milestones with a deadline for finding a candidate build, and another for making sure the build is ready to go live.
General Availability (GA)
This is the end of the release cycle. The last release candidate build is made available to the public.

Deferring P1 and P2 bugs

Even though there’s nothing explicitly written in the process about deferring P1 and P2 bugs during the initial development phase, the assumption is that these aren’t deferred unless time runs out at the end of the release cycle.

Please note that the priority of a bug doesn’t change just because you want to get your fix in late in the release, or if you want to be able to defer it. The priority is based on the severity of the bug and if it was deemed to be a P2 before, you better have a really good explanation to why that conveniently has changed by the end of the release. Being hard to fix is not a reason to lower the priority of a bug.

Forward ports

During the rampdown of a release there are two repositories in play, the stabilization fork for the outgoing release, and the mainline repository where the next release is being developed. Any bugfix going into the stabilization fork is likely to be desired in mainline as well. As a developer you should push your fix to the stabilization fork only, even if you intend for it to go to both repositories. Your fix will be forward ported to mainline.

All fixes that are pushed to the stabilization fork are forward ported to mainline. If you have a fix that is only intended for the stabilization fork you will have to manually back it out from mainline once it has been forward ported. In order to remember to do this you should file a backout isue in JBS before pushing your change to the stabilization fork. E.g., To push JDK-xxx to the stabilization fork but not to mainline, you need to file an issue, JDK-yyy, in JBS to back out the fix after it has been merged into mainline. Make sure the two JBS issues (JDK-xxx and JDK-yyy) are related so that it’s easy to find one from the other.

To clarify, as soon as you know that there is a fix that needs to go into the stabilization fork but not mainline, you should do the following:

Then, you have to wait until the JDK-xxx fix is forward ported to mainline before actually fixing JDK-yyy. Making these settings in JDK-yyy will help ensure that it won’t be missed.

There are also examples in JBS where JDK-yyy has been created as a sub-task of JDK-xxx. This works, but isn’t recommended since JDK-yyy stands a higher risk of being missed when it’s not of type Bug but rather a sub-task of an already closed issue. Also see Backing out a change for reference.

To the top

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

Directory to area mapping

To the top

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) Please let us know if there’s anything in the guide that isn’t clear.


provisional (in the CSR)
The stage of the CSR 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.
approved (by the CSR)
The stage of the CSR process after “FINALIZED”. The CSR has approved the final version of the request which permits push into the project repository.
A collection of changes with respect to the current clone of a repository.
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/ can be used to apply a Mercurial hg command to all the repositories in a forest.
A directory tree in the filesystem that Mercurial treats specially. This tree contains the source files and their revision history.
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.
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.

To the top

File change revision: 6db7388 - Revision history