Introduction

Welcome to the OpenJDK Developers’ Guide!

The OpenJDK Community is the place to collaborate on open-sourceimplementations of the Java Platform, Standard Edition, and relatedProjects. It wascreated in November 2006, when initial portions of the JDK sourcecode were published under the GPLv2 license.

In order to work together efficiently, clear directions aresometimes needed to avoid misconceptions and to aligndevelopers’ views of terminology and process. The OpenJDKCommunity is a fairly pragmatic place. “Do the rightthing” is most often the right course of action. Still, ifpeople do things in the same right way then everyone’s workbecomes more transparent and easier for others to follow. For thisreason most parts of the development process have standard flowsthat are the recommended ways to do things.

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

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

OpenJDK

OpenJDK consists of a number ofGroups. Members of aGroup collaborate onan area of mutual interest. The right hand side bar on theOpenJDK website has a list of allGroups in OpenJDK.If you’re interested in a specific area, this is where youwould start your OpenJDK experience. Look at theGroup’s informationand wiki pages, and see whatProjects they sponsor ontheCensus page. TheCensus shows the structureof the OpenJDK Community.

Projects arewhere the coding and much of the other work is done in OpenJDK.There are many differentProjects, some produceshippable artifacts, like theJDK Project, some producetools to be used by developers of these artifacts, like theCode ToolsProject orProject Skara, and someproduce documentation, like theDevelopers’ GuideProject. ManyProjects designs anddevelops new features for the Java language or the JVM, but thereare also less code centric ones like theDuke Project whichcollects images of the Java mascot, Duke.

Author, Committer, Reviewer

OpenJDK has a few different roles that determine who has theright to do what in the differentProjects. These roles aredefined in theOpenJDK Bylaws. Theroles are earned based on experience and knowledge within eachProject.

AContributor can havedifferent roles in differentProjects. Whenyou’re new to aProject you don’tyet have a formal role in that specificProject, even though youmight have earned roles in otherOpenJDK Projects or havebeen recognized as aContributor or aMember ofOpenJDK. By contributing high-quality content you’ll soon beeligible forOpenJDK roles in theProject. FirstAuthor, thenCommitter, andfinallyReviewerif you stay active and earn the trust of the community. Trust is animportant part of earning these roles. There’s arough guideline saying that tobecome aCommitter you shouldhave contributed 8 significant changes, and to become aReviewer you should havecontributed 32 significant changes. In reality it’s not aseasy as “just” contributing code. You need to build atrack record of good decisions and sound judgment and show that youknow 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 trustyou’ve earned is put to the test through a vote.

Note that when a newProject is created aninitial set of members can be brought in at different levelswithout a vote.

Becoming an Author

Becoming anAuthor is the first step.To achieve this you need to contribute two changes to theProject in which you wishto become anAuthor. Once your changesare integrated into the code base and has been vetted enough todetermine that the changes were indeed good changes you can goahead and send an email to the Project lead of that particularProject and ask tobe added as anAuthor. Note that“theProject” is notOpenJDK, but rather the specificdevelopment Project whereyou did your contributions (e.g. “JDK”, “JDKUpdates”, “Amber”, etc). TheOpenJDK Projectdescription has a template for such an email. In short theemail should contain your name, the Project name, your emailaddress, and GitHub links to your changes. In response to youremail you will get a time-limited invite which you should fillout.

To see who the Project lead is for yourProject, see theOpenJDK Census. TheCensus unfortunately doesn’tprovide email addresses for people, but assuming you have beenactive on the Project mailing list (since you are applying forAuthor after all),you should be able to find the lead’s email address in yourlocal email archive, or ask yourSponsor.

As anAuthor youwill get your OpenJDK user name. Once you have gotten the username, this should be associated with your GitHub account in orderfor the bots to be able to identify you onGitHub. See theSkara documentation for more details on that. Once that’sdone you can create PRs and get them reviewed, but you’llstill need aSponsor to integratechanges. You’ll also get write access toJBS and theOpenJDK wiki related to theProject in question, andtocr.openjdk.org via an SSHkey provided at the time you accept your invitation.

The rules of any particularProject may have differentguidelines regarding requirements for Authorship at the discretionof the Lead.

Becoming a Committer

To become aCommitter you shouldshow that you intend to actively contribute to theProject and that you canproduce non-trivial changes that are accepted for inclusion intothe Project code base. The number eight has been seen as a formallower limit on the number of changes, but since the changes must benon-trivial, or “significant” as theOpenJDK Project descriptionsays, and the definition of significant is subjective, the generalrecommendation is to wait with aCommitter nominationuntil there’s at least 10-12 changes integrated to have somemargin for different interpretations of “significant”.In practice though, we have seen several examples where the numberof significant changes hasn’t been the dominating factor in aCommitter vote.AContributor’swork in anotherOpenJDK Project may alsobe relevant for the vote. What the vote should ultimately test istheContributor’scommitment to theOpenJDK Project for whichthe vote applies - is it believed that the person is dedicated andwilling to spend time and effort on theProject? Is the personbelieved to be a good citizen of theProject? It’s alwaysa good idea to seek the advice of aSponsor who can guide youthrough the process to becoming aCommitter - you willneed one to run the Committer vote anyway. They will probably alsohave a better idea of what constitutes a “significant”change.

Once you have the required changes, aCommitter in theProject can starta vote by sending an email proposing that you should become aCommitter. Theemail should follow the template found in theOpenJDK Projectdescription.

ACommitteris allowed to integrate changes without the aid of aSponsor. ACommitter is alsoallowed to nominate other non-Committers to becomeCommitters in theProject.

Becoming a Reviewer

To become aReviewer you must show atrack record of sound and correct judgment calls as mentionedabove. Being a goodCommitter doesn’tnecessarily make you a goodReviewer. As aReviewer you have thepower to approve changes for inclusion into the Project sourcecode. This means that aReviewer needs to be ableto judge the quality and appropriateness of any proposed change,not just the mechanics of the code.

The assumption is that after having produced 32 significantchanges one should have become familiar with the process aroundreviews and the requirements around getting a change approved. Thisshould really be seen as a minimum requirement though. A morepractical consideration would be to look at whether the non-trivialcommits of a potentialReviewer are acceptedlargely intact or whether they are always being refined by thereview process. There may be cases where it will take significantlymore than 32 changes for aCommitter to be ready tobecome aReviewer.

Once you are deemed ready, aReviewer in theProject can start a voteby sending an email proposing that you should become aReviewer. The emailshould follow the template found in theOpenJDK Projectdescription.

Non-trivial/Significantchanges

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

Instead of describing the significant change (becausethat’s quite difficult to define) provided here is a fewexamples of changes that wouldn’t be considered significantor for other reasons wouldn’t count as significantcontributions.

• Purely aesthetic changes like renaming or fixingindentation
• Repeated follow-up bugfixes from earlier changes
• Larger changes where only a non-significant portion of the workwas done by theContributor undervote
• Trivial backports of someone else’s changes

Contributing to anOpenJDK Project

Contributing to OpenJDK can take many forms. Writing code andproviding patches is just one of them. A big part of developing afeature or a bugfix is testing and code review. Anything you can doto help out in these areas will be recognized as a contribution.Join themailing lists to engage indesign discussions and reviews, and download the latest EA buildsor Project repositories to try out new features and give feedback.If you see some misbehavior, or if you see somebody mention somemisbehavior on some internet forum, try to track it down. Good bugreports with reproducible test cases are extremely valuable andmake excellent contributions.

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

If you have a success story where Java solved your problem, orif you successfully upgraded to a more recent version of the JDKand 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 programminglanguage to use in a project, in a tutorial, or in a class, youhave the power to enlarge the Java community in a very direct way,and your colleagues or students will get an opportunity to learnone of the most used programming languages in the world.

Things to consider before proposing changes to OpenJDK code

Every change to JDK code carries a risk of changes in behaviorwhich may adversely affect applications. Generally we’relooking to improve the functionality and capability and sometimesperformance of the platform without that negative consequence. Sowe need to ask ourselves whether each change is worthwhile - andsome may not be no matter how well intentioned.

One question to ask yourself is:What problem are youtrying to solve?

The important thing here is to understand the problem itself,independent of any solution (and independently of the solution thatcurrently happens to be in your change). A number of otherquestions and lines of thought emanate from thinking about theproblem. For example: is this the right problem to solve? Doessolving this problem create worse problems elsewhere; that is, isthere a net benefit? Does this problem need to be solved in theJDK, or can and should it be solved elsewhere (e.g., intooling)?

The next question you need to answer before making any changeis:What is the main intention of your change?

Depending on your answer to that question you will need toconsider one or more of the following paragraphs.

• Correctness – If your change improvesprogram correctness, that’s important. And to broaden this,fixing of all kinds of bugs that really make things better forapplications in ways they can detect is important.

• Robustness – Updating code to use a newerplatform API can be a good change. Moving away from APIs that arebeing deprecated or that are no longer maintained is likelydesired. Do note though that supposedly equivalent APIs may not bethe drop in replacement you think they are. You’ll need toprove that the code has the same behavior after the change throughextensive testing.

• Security – If you intend to increase theoverall security of the platform, changes following secure codingpractices and using appropriate platform APIs for that are usuallywelcome. The exception might be if it’s a potentiallydestabilizing change in code where there’s only a theoreticalproblem.Please note: If you think you found areal security bug that might compromise the platform you shouldfollow the processhere.

• Refactoring / Cleanup – Making codeeasier to understand or reducing code size may be a good change inareas that are under active development. Stable code howeverisn’t a good candidate for refactoring regardless of what thecode looks like. The OpenJDK has evolved over many years and someparts have been stable for decades. If there’s no immediateneed to work on the code for other reasons, then what will acleanup actually achieve? One specific area where refactoring andcleanups are explicitly discouraged is in third-party code.

• Performance – Can you demonstrate a userperceptible change? If you can’t measure the change, or auser can’t notice the change, or the change only improvescode that is used infrequently, then maybe it isn’t worth it.Do you have benchmarks to back up your claims? Do you understandthe results? Performance testing is complex and often there aremany factors unrelated to your change that affects the numbers.What’s the tradeoff? The performance improvements that justmake everything better do exist, but they are extremely rare. Mostoften the code gets more complex, or you speed up one case but slowdown another. Are you making the right tradeoff?

• Modernizing – Changing code purely forthe sake of using a new language feature isn’t usually a goodchange. Be a subject matter expert, not just a language expert.Writing code in “a better way” is not guaranteed to besafe. A change of behavior is always possible and unless youunderstand the code you are changing at more than the corelanguage/API level, and have looked into appropriate tests and canspeak to the risks, then you should first find a subject matterexpert to discuss it with. Keep in mind that the OpenJDK code isdeveloped by a large community. If a new language feature isintroduced, all developers working in that code must learn this newfeature and understand the implications of using it.

I have a patch, what do Ido?

In many GitHub projects the standard way to propose a change isto create a pull request (PR) and discuss the patch in the PR. ForOpenJDK Projectsthe situation is somewhat different. The JDK is used for missioncritical applications and by millions of developers, the bar tocontributing changes is high. Please follow the steps outlinedbelow to make sure your change passes above the bar before creatinga PR.

1. Sign the OCA

Like many other open-source communities, the OpenJDK Communityrequires Contributors to jointly assign their copyright oncontributed code.Oracle isthe steward of OpenJDK and if you haven’t yet signed theOracle ContributorAgreement (OCA), and are not covered by a company-levelagreement, then please do so. This is required in order to makeyour patch available for review. The OCA givesOracle and you as a Contributor jointcopyright interests in the code. You will retain your copyrightwhile also granting those rights toOracle. If you don’t know ifyour organization has signed the OCA you can check theOCASignatories List, or ask your legal advisor.

When you sign the OCA, please make sure that you specify yourGitHub user name in theUsername field of the OCA. Ifyou try to create a PR before you have signed the OCA, or if youdidn’t specify your GitHub user name, you’ll getinstructions telling you to do so, and the PR won’t bepublished until this is done. OCA registration is a manual process.Please allow for up to several days to have your OCA applicationprocessed, even though it’s normally processed swiftly. Analphabetical list of all of the assigned OpenJDK usernames can befound on theOpenJDKpeople list.

You only need to sign the OCA once in order to cover all changesthat you might contribute to any Oracle-sponsored open-sourcecommunity. If you’ve already signed the OCA or the former SCA(Sun Contributor Agreement) for any Oracle-sponsored open-sourcecommunity, then you do not need to sign it again in order tocontribute to OpenJDK. Please note that you don’t need tosign an OCA if you work at Oracle or a company which has negotiatedan equivalent agreement.

2. Socialize your change

Once the OCA is signed, please restrain your urge to create a PRjust a little while longer. In order to prepare the community foryour patch, please socialize your idea on the relevantmailing lists. Almost all changes, and inparticular any API changes, must go this route and have a broadagreement in place before there is any point in presenting code. Tounderstand the criteria by which your patch is going to be judged,please readWhy is My ChangeRejected? below. In short, hidden constraints and assumptions,stability and quality, maintainability, compatibility, andconformance to specifications must be considered before your PR isready to be submitted. If you don’t understand theconstraints for acceptance, you might be surprised when your PR isrejected.

Please note that lack of engagement should not be interpreted assupporting the proposal. Lack of engagement might be betterinterpreted as people are busy or maybe that the problemisn’t compelling or high priority enough to spend time onright now. If you didn’t get the desired attention and therequired agreement in your mail thread,do notproceed to create a PR.

3. Find a Sponsor

Socializing your change on the mailing lists also prevents thesurprise that would otherwise make the community choke on theirmorning coffee when they see a huge patch in a new, unknown PR. Asa new developer in the community you’ll need to make a fewfriends that agree with your change. There are many good reasons tomake friends, but the one relevant here is that for your firstchanges you’ll need aSponsor to facilitate theintegration of your work. TheSponsor will perform anynumber of administrative tasks like JBS updates, additionaltesting, etc. It’s usual for aSponsor to also be areviewer of a change and thus familiar with it, but it’s nota requirement.

4. Create a tracking issuein JBS

ManyOpenJDKProjects require a tracking issue to be filed in theJDK Bug System (JBS) before achange can be integrated. This is the case for instance for the JDKand the JDK Updates Projects. In order to obtain write access toJBS you need to be anAuthor in anOpenJDK Project (seeBecoming an Author). For yourfirst changes, ask yourSponsor to help you createthe issue or file the bug through theBug Report Tool.

5. Get acquainted withlocal process

Even though we strive to unify how things are done withinOpenJDK, different areas andProjects in OpenJDK mayhave slight variations in how they work. Some of these differencesare highlighted throughout this guide, some aren’t. Ifyou’re new to an area, make sure you understand localdifferences before you proceed. Ask yourSponsor who should be yourmain point of contact through your first developer experience inOpenJDK.

Why is my change rejected?

Just about every Java developer out there has an idea or two forhow to enhance something. And believe it or not, not every idea isa good idea. Even though many ideas are indeed good, we must bequite restrictive on what we actually include into the JDK. Thegoal is not to take in the maximum number of contributionspossible, but rather to accept only the highest-qualitycontributions. The JDK is used daily by millions of people andthousands of businesses, often in mission-critical applications,and so every change must be scrutinized in detail. There are manyreasons for this.

• Hidden constraints and assumptions – Manysections of code have constraints and assumptions that aren’tnecessarily visible at first glance. This might preclude certainchanges, even those that might seem obvious.

• Stability and quality – The JDK is usedby millions of developers and as a widely deployed commercialproduct, it’s held to a high standard of quality. Changesshould include tests where practical, and core tests should pass atall times. The value of the change should outweigh the risk ofintroducing a bug or performance regression.

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

• Complexity – Each new feature interactswith all the existing features, which can result in geometricgrowth of the interactions among features if features are addedunchecked. Sometimes we avoid adding a new feature, even if itseems like an obvious thing to add, if that feature would make itdifficult to add a more important feature in the future.

• Adherence to specifications – Much of theJDK is governed by a series of specifications, in particular theJava LanguageSpecification, theJava Virtual MachineSpecification, and theJavaAPI Specification (“javadocs”). All changes must bechecked and tested carefully to ensure that they don’tviolate these specifications.

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

• Specification changes – It’spossible to change the API specifications, and this is doneregularly. However, these changes require even more scrutiny thancode changes. This extra review is handled by theCSR Process.Specifications are written in stylized, somewhat formal language,and they don’t simply describe what the code does. Writingspecifications is a separate skill from coding.

• Compatibility – Changes should alsoadhere to high standards of binary, source, and behavioralcompatibility. The compatibility impact of apparently innocuouschanges is sometimes startling.

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

If you’re relatively new to the Java platform then werecommend that you gain more experience writing Java applicationsbefore you attempt to work on the JDK itself. The purpose of thesponsored-contribution process is to bring developers who alreadyhave the skills required to work on the JDK into the existingdevelopment community. The members of this community have neitherthe time nor the patience required to teach basic Java programmingskills or platform implementation techniques.

The feature releases currently under development are in the JDKProject. Most development work is focused on the newest release, sogenerally you should be working against the latest JDK sourcesrather than the JDK Updates sources.

Mailing Lists

The mailing lists are the key communications mechanism for allOpenJDK work. All participation in anOpenJDK Project startswith joining the relevant mailing list. A subscriber to an OpenJDKmailing list is referred to as aParticipant in theBylaws. As a generalrecommendation we suggest to subscribe toannounce,discuss,and the-dev lists covering your explicit area ofinterest. All OpenJDK mailing lists are found here:

mail.openjdk.org

The OpenJDK Community is a friendly place. To keep it that wayit’s important to keep a professional tone in emails and beaware that the community is global. Many different people withdifferent backgrounds collaborate in these lists. Even thoughEnglish is the required language for all lists, many Participantsspeak other languages as their native language. A high tolerancefor non-perfect English is expected from anyone joining theselists. You’re also strongly encouraged to use your real nameon the mailing lists. This adds to the professional tone of youremail. Postings from anonymized mailboxes risk being seen as spam.If you do work in OpenJDK on behalf of your employer, please alsolist this affiliation. If your GitHub username differs from yourreal name it’s also a good idea to include that to identifyyourself and your actions onGitHub.

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 listhas its own archive where you can browse older conversations on thelist.

There are a few different types of lists. The list name has twoparts to explain what the list is intended for,<name>-<suffix>. The name often refers totheProject thatowns the list or a specific area of interest that the list focuseson. The suffix is explained below. Not allProjects or areas have alltypes of lists described here.

-dev

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

-use

Technical discussions around the usage of the Projectartifacts.

-discuss

General discussions around theProject. The special casediscuss@openjdk.org is used for general discussionsaround OpenJDK. Discussions around new Project proposals usuallyhappen here.

-changes

Changeset notifications from the source code repositoriesmaintained by theProject.

-announce

General Project announcements. These lists are tightlymoderated and are expected to be low traffic. The special caseannounce@openjdk.org is used for announcements forOpenJDK.

-experts

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

-observers

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

-comments

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

Changing your emailaddress

If you need to change your registered email address, or if youhave any other problems with the mailing lists, please contactmailman@openjdk.org.

Code Conventions

JBS - JDK Bug System

JBS is a public issuetracker used by manyOpenJDK Projects and isopen for anyone to read and search. To get write access you need tobe registered in theOpenJDKCensus by becoming, for instance, anAuthor in anOpenJDK Project.

Filing an issue

When a new failure is found, or an improvement identified, anissue should be filed to describe and track its resolution.Depending on your role in OpenJDK you can either use theBug Report Tool or, if you areregistered in theOpenJDKCensus, you can report the issue directly inJBS.

When filing an issue, try to make the report as complete aspossible in order to make it easier to triage, investigate andresolve the issue. Bug descriptions and comments should be writtenin a professional manner.

A few things to keep in mind when filing an issue:

• Before filing, verify that there isn’t an open issuealready filed.
  • SearchJBS for thingslike the name of the failing test, assert messages, the name of thesource code file where a crash occurred etc.
  • If you find a similar issue that was closed asCannot Reproduce then it may be appropriate tore-open that one - if you don’t have direct access to JBS youcan file a bug using theBugReport Tool requesting that it be reopened.
• Make a reasonable attempt to narrow down which build or releasethe failure first appeared in.
• SetAffects Version/s to theearliest JDK version where the failure was seen.
  • If the failure is found in an update train of the JDK(e.g. 11.0.x), please see (if possible) if it’s alsopresent inmainline.SeeIndicatingwhat releases an issue is applicable to for more details.
  • All issues of typeBug must havetheAffects Version/s set.It’s not a bug if it doesn’t affect some version.
  • For enhancements theAffectsVersion/s should be left empty, unless it is only relevantto a specific release family.
• Add relevantLabels likeintermittent,regression,noreg-self,tier1 etc.
  • For more information see theJBS Label Dictionary.
• Set the priority.
  • It’s not the reporter’s responsibility to set acorrect priority, this will be done later intriage, but a qualified guess is alwaysbetter than the default. In JBS the range of priorities go from P1(High/Important) to P5 (Very Low/Not Important), with the defaultbeing P4.
  • If you have a sense that the issue is critical, or not criticalat all, then adjusting the priority higher or lower makes sense,otherwise you can leave it as the default.
  • When setting the priority, consider things like how the bugimpacts the product and our testing, how likely is it that the bugis triggered, how difficult is it to work around, and whetherit’s a regression, since that may break existingapplications. Regressions are often higher priority thanlong-standing bugs and may block a release if not fixed. An exampleof a P1 would be an issue that is blocking a build or a release,whereas a P5 would be a minor typo in a code comment.
• In theDescription, alwaysinclude (if possible):
  • error messages
  • assert messages
  • stack trace
  • command line information
  • relevant information from the logs
  • full name of any failing tests
• Avoid including in the report:
  • personal information
  • passwords, logins, machine names
  • logs which may include sensitive data
  • large amount of text or data - large logfiles are betterprovided as attachments
• If the failure isn’t reproducible with an existingOpenJDK test, attach a reproducer if possible, having a test casewill decrease the time required to resolve the issue.
• In general theCPU and/orOS fields should not be set.ONLY use them if you know that the issue is onlyrelevant to a particular platform or set of platforms.
• Provide the output ofjava -version wheneverpossible - this version information is particularly critical forhangs, JVM bugs, and network issues.
• Always file separate bugs for different issues.
  • If two crashes look related, but not similar enough to be surethey are the same, it’s easier to later close a bug as aduplicate than it is to separate out one bug into two.

Types of issues

The most common issue types are:

Indicating what releases an issue is applicable to

Knowing when an issue was introduced is important to determinethe impact of the issue and where it needs to be resolved. While insome cases it may be clear, it is likely that on submission andduring triage this won’t be known, instead we will have oneor two data points from which we can begin to understand the rangeof releases which the issue impacts.

TheAffects Version/s field isused to indicate which releases an issue is applicable to, and toavoid having to set it to an exhaustive list of impacted releasesthe following assumptions are used to give that range:

1. If an issue is applicable to a feature release N, it is assumedto be applicable to all (more recent) releases unless indicatedotherwise (see(Rel)-nabelow).
   • Note that if it’s reported against an update release thenall we can say is that it’s applicable to all the followingupdate releases, not necessarily the next feature release as it mayhave been introduced in an update. Given this, it is alwaysimportant to try and reproduce the issue in the correspondingfeature release as well as mainline.
2. If an issue is applicable to release N, then it can’t beassumed that it is applicable to older releases less than N. It maybe, but in general this is less important to know, as the majorityof issues are only fixed in the latest feature release. If theissue is a crash or important in another way, then it becomesworthwhile to take the time to determine if it’s relevant toearlier LTS releases.

Another aspect is when the impacted code was added or removedfrom the JDK, which in either case limits the range of releases theissue impacts. Knowing that a feature was removed before the oldestcurrently maintained release means it can be resolved asWon’t Fix.

Setting the AffectsVersion/s field

Set theAffects Version/s fieldto the lowest release where the bug has been seen.

• TheAffects Version/sisn’t meant to be an exhaustive list of releases the issue isrelevant to - it should initially be set to the release the issuewas reproduced or identified on, and by implication it will berelevant to all releases past that point (seeUsage of the (Rel)-na Label). If it’s later found to beapplicable to an earlier release family then adding that earlierrelease is encouraged if the issue needs to be fixed in thatrelease.
• Don’t add additional release values toAffects Version/s for the same release family.For example, if there is the value11.0.2, don’t add11.0.5,11.0.7etc. Adding an additional value for a separate release family whereit’s still reproducible, e.g. JDK21, is encouraged if there isn’t currentlya feature release value set, or, it has been a few releases sinceit was last reproduced/reviewed. For example, if theAffects Version/s is JDK8, but it is still relevant to the latestmainline release.

Usage of the (Rel)-na Label

Labels of the form (Rel)-na (eg.17-na) should be used when a bug isnot applicable to a more recent release family. For example:

Affects Version/s:7u111,8u131

add the label9-na if the issueis not relevant to JDK 9 and above. Reasons why this would be thecase include the fact that the source has been removed from a laterrelease or rewritten such that the issue is no longer relevant.

Don’t:

• use the label to indicate that a bug is not relevant to anearlier release, for example

  Affects Version/s:11.0.20,17

  the label8-na would not beneeded - as it doesn’t have a JDK 8 release, or earlier,value in theAffects Version/s, itis not relevant to JDK 8. Also seeUsage of the (Rel)-wnf Label

• add multiple-na labels: you onlyneed one, for example don’t add both9-na and11-na—9-na implies all followingreleases therefore11-na, or17-na etc. are not needed.

• It’s not recommended to specify update releases like 17u4or 21u in the label. Labels like17-na and21-naare in general enough.

Usage of the (Rel)-wnfLabel

Labels of the form (Rel)-wnf(e.g. 11-wnf) should be used toindicate that a bug is not going to be fixed in a release thatit’s applicable to, or any earlier releases. For example,11-wnf states it won’t befixed in JDK 11 and implicitly indicates it won’t be fixed inJDK 8 either.

Add a comment when adding a (Rel)-wnf label so that it’s clear for thoselooking at the issue, why it won’t be fixed in thatrelease.

Examples

Guidelines for settingAffects Version/s

1. Issue relevant to JDK 8 and all future releases.
2. No need to add additional releases as they are implied.
3. Adding the occasional LTS release value is ok.
4. Use N-na to indicate that the issue is no longer relevant fromthat release, which could be due to the feature or platform beingremoved or the code being rewritten.
5. Use N-wnf to indicate that a fix will not be backported to thatrelease, or earlier.

Things to keep in mind when requesting an improvement

Unlike reporting a problem, when it comes to improvements, whatconstitutes a reasonable request can take discussion, and ingeneral it’s encouraged that themailing list for the area is used to suggestan improvement before filing.

Enhancements to the Java Language Specification and the JVMSpecification are managed through theJava Community Process.

To find out which component to use for different bugs, consultthedirectory to areamapping.

Implementing a largechange

When managing the work for a large change, especially when thework involves multiple engineers, it’s recommended that thework is distributed across one or more “implementation”issues which should be linked to the main enhancement with a“blocks” link along with any relevant CSRs. Theenhancement shouldn’t be considered done until all theblocking elements are completed. The use of sub-tasks forenhancements is not recommended unless all the sub-tasks arerelevant to the fix, if it were to be backported, for exampleJDK-8231641 orJDK-8171407.

Implementing a JEP

It’s recommended forJEPsthat the implementation is spread across one or moreEnhancements as described above.

Issue states

JBS only has a few states in which aBug orEnhancement can be:

JBS Issue Flow

Triaging an issue

For most JDK areas, triage is performed on a regular basis (atleast weekly) by triage teams. Each triage team consists ofContributorswho are area experts for a specific area or feature. If youhaven’t been selected to be part of a triage team for aspecific areayou shouldn’t be triaging bugs in thatarea.

When triaging an issue, first give it a general review.

1. If the issue is a duplicate, close it as such.
2. If the issue belongs to a different area (it was filed inlibraries, but it’s an HotSpot issue), transfer it to thecorrect component/subcomponent making sure that the state remainsNew.
3. If the issue is incomplete, add a comment noting what is neededand resolve the bug asResolved -Incomplete. This is the JBS way ofsaying “need more information”. If no more informationis obtained within reasonable time, the issue should be closed(Closed -Incomplete).

Now that the issue is in the right component and has the basicinformation, the analysis continues to get a more detailedunderstanding of the issue, and what should be done:

1. Ensure the priority is correct.
   • An approach that has been used for getting a consistent view ofpriority is to consider three aspects of the issue:Impact of the issue;Likelihoodof it occurring; and, whether there is aWorkaround. The higher the impact and likelihoodthe higher the priority; then, having a workaround reduces thatpriority - but mostly where the impact and likelihood aren’tthat severe.
2. Ensure theAffects Version/sfield is correct (within reason).
   • This may involve reproducing the bug, if doing so is fast andeasy.
   • In addition to the version where the bug was found, takespecial care to also investigate if the bug affects mainline.
     • SeeIndicatingwhat releases an issue is applicable to for more details.
   • For enhancements theAffectsVersion/s should be empty unless you feel that theenhancement is only relevant to a particular release family, andshouldn’t go into a future mainline release.
   • Affects Version/s should neveruse any of the “special” values available in JBS liketbd,na,unknown,(Rel)-pool or similar. Only actualJDK release numbers should be used. If you want to reflect that anissue is relevant to an older release, use a family release valueor an exact release if you know where the issue was introduced:8,17,21u4.
3. Set theFix Version/s.
   • A bug should be fixed first in the most recent version where itexists. If you don’t know what version the fix will go intoset theFix Version/s totbd or the appropriate(Rel)-pool if the fix is for a specific releasefamily. If there is a(Rel)-pool inthe fix version Skara tooling will use that issue/backport when youintegrate the fix for that release family.
   • If the bug also exists in older versions it may requirebackporting.
     • The decision to backport to a release should be made inlinewith the guidelines of the lead for that release.
     • There are two options for creating backport issues to track thebackport: one is to create it manually once it’s agreed thatthe bug should be backported; the second, is to let the bots createthe backport issue once you integrate the fix to the repository(seeWorking withbackports in JBS). In most cases, letting the bots create thebackport issue is preferred.
   • For Project internal changes intended to be integrated to aProject repository rather than the JDK or JDK Updates repositories,theFix Version/s should be set tointernal, or if theProject is large enough tohave its ownrepo-* fix version, usethat.
   • Only oneFix Version/s shouldever be set. If the issue is to be fixed in additional releasesthen separate backport issues must be created (seeWorking with backports inJBS). There are exceptions to this rule for CSRs and ReleaseNotes.
4. Make sure the bug has all the required labels – seeJBS Label Dictionary.
   • Changes that don’t affect product code, but are onlyagainst the regression test, or problem-listing:noreg-self
   • Changes that don’t affect product code, but are onlyagainst documentation:noreg-doc
   • Well contained issues that seem to be easy to fix:starter
   • Enhancements that are pure cleanups:cleanup
   • Project specific issues usually have their own labels aswell
5. Managing regressions - for a bug (B) where behavior hasincorrectly changed from a previous fix (A) ensure thatthe labelregression is added. Once it is known whatfix caused the regression acausedby link should be added to ‘B’ or acauses link to ‘A’. Acauses link would also be added to A if the fixcauses a change of behavior (intentional or otherwise) orit is found after integration, that additional work needs to bedone. In addition to adding acausedby link, set theIntroduced inVersion andIntroduced inBuild fields of ‘B’, based on which release‘A’ was fixed in. Do not add acaused by link if there was no specific productfix whichcaused it, for example, the addition of a testwhich finds an underlying problem should not be linked.

At this point move the issue into theOpen state.

Sensitiveinformation (e.g. hs_err.log)

It may sound obvious, but avoid placing sensitive information inbug reports. Things like usernames, IP addresses, host names, andexact version information of third party libraries etc. may becrucial to be able to debug in some cases, but could also help anattacker gain information about your system. JBS is a publicdatabase that anyone can search, so be mindful of what you placethere. In particular when attaching log files like the hs_err.logyou should make sure that you are comfortable sharing the detailsexposed in it. Sometimes it may be better to leave a comment sayingthat these details can be obtained on request.

If you file a bug through theBug Report Tool there’s aspecific field that should be used to place sensitive informationlike this. Information placed there will not be part of the publicbug report.

Updating an issue whilefixing

Once you are made, or you make yourself, the assignee of anissue you take on the responsibility of moving the issue through toresolution - providing the current status, and ultimately leaving arecord for others in the future to understand what happened. Thereare no set rules for how you manage the bug while you are assignedto it, as it depends on the type and importance of an issue. Asimple update to the doc needs little to be done, fix the problemand close the issue; an intricate timing issue or crash should behandled differently - documenting your progress in identifying theproblem (e.g. JDK-8212207,JDK-6984895,JDK-8287982),this is especially helpful if you ultimately move the issue to adifferent area as you have found that the problem lies elsewhere,or is closed asWon’t Fix.Your updates then provide a resource to others to better understandwhat has been done or the code itself. SeeThe Importance of Writing Stuff Down for a good explanation asto why it’s important.

Some additional fields should be filled out or updated as youget a better understanding of the issue:

• TheDescription usually explainswhat went wrong and how the failure was found, then there’ssome investigation and eventually the root cause is found. At thispoint theSummary should be updatedto correctly describe the bug. TheDescription however should remain a descriptionof how the failure was found.
• TheAffects Version/s should beupdated if you in your investigation finds that the issue is olderthan what is indicated by the currentAffects Version/s.

Linking Issues

An important aspect of any issue is making clear how it isconnected/related to other issues. This can occur at any stage ofthe issue’s lifecycle. For example, as information becomesavailable that might suggest a cause, or similar issue (relatesto).

There are the following link types:

Resolving or Closing anissue

Once the work on an issue has been completed the issue’sStatus should be in a“completed” state. There are two“completed” states:Resolved andClosed. These are accompanied by aResolution and aFixVersion/s. Which combination ofStatus,Resolution, andFixVersion/s you should use depends on how the issue iscompleted.

Most resolutions are used to close an issue so that it ends upbeingClosed directly, butresolutions that indicates that a change has been integrated into aProject repository must go through theResolved state. An issue inResolved state needs to go throughverification to end up asClosed. For the JDK Project in almost all casesthe bots will transition the issue toResolved/Fixedwhen the changeset is integrated to the repository.

TheFix Version/s field shouldindicate when an issue was fixed. The most common value for thisfield is a JDK version number. There are some special valuesavailable for this field in JBS, these should only be used forspecial cases as outlined in this Guide.

Closing issues asduplicates

If the same issue is described in another JBS issue then closeone against the other asClosed/Duplicate.In general the newer issue is closed as aDuplicate of the older one, but where the newerissue has a clearer description, or more useful, up-to-datecomments then doing it the other way round is ok as long as none ofthem has beenFixed already. If oneof the issues has beenFixed theother one should be closed as aDuplicate of theFixed issue. There may be other reasons tochoose to close one or the other issue as theDuplicate. As always - use your best judgementto make the end result as good as possible.

Closingissues without knowing what fixed it

If it’s determined that an issue has been fixed, butit’s unknown what change that fixed it, closing asFixed is not an option as thisrequires a changeset in a project repository.Duplicate is also not an option since thisrequires a duplicate-link to the issue that fixed it. A common wayto handle such cases is to close the issue asDelivered with theFixversion/s set tounknown.Closing an issue asCannot Reproducehas also been common practice but is no longer recommended ifit’s known that the issue has actually been fixed.

Closing incomplete issues

As mentioned above, issues that lack the information needed toinvestigate the problem are placed in statusResolved -Incomplete. Triage teams should monitorincomplete issues in their area and if needed ping the relevantperson. When new information is received, the bug should bereturned to statusOpen. If therequired information hasn’t been obtained within reasonabletime (3-4 weeks) the bug should be closed asIncomplete.

Verifying an issue

Once an issue is marked as resolved there is now the option ofsomeone, other than the person that fixed it, of marking it asVerified to confirm that the issueis fixed after testing; marking it asFixFailed if it didn’t solve the issue; or,Not Verified to indicate that it wasn’texplicitly tested. Note that the JBS UI doesn’t highlightwhenFix Failed has been set, youneed to look for theVerificationfield at the bottom of the left-hand column in the Detailssection.

Removing an issue

Removing a JBS issue is a rare extreme case that shouldn’tbe part of the normal workflow. For this reason, removing issues isrestricted to admins only. If you for some reason need to remove anissue, send an email toops@openjdk.org. You need to providethe bug id and a well considered reason the issue should beremoved.

Note that JBS issues are not removed just because something wasa bad idea, or a reported issue turned out to be an embarrassinguser mistake. Such issues are simply closed.

JBS labels

JBS labels are used to tag and group related issues. JBS labelsare an open namespace, which means that anyone can create newlabels at any time. In order to avoid confusion, however,it’s best to reuse existing labels where possible. Most areashave their commonly used labels to identify issues in theirrespective area. Make an effort to find and use these labels. Thiscan be done by editing theLabelsfield of a bug and entering the first few characters of the labelyou want to add. JIRA will pop up an autocomplete window withexisting labels that match that prefix. Then choose one of theexisting labels. Using the autocomplete window is preferable totyping 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 spuriousspelling variations.

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

JBS label dictionary

This table contains some frequently used JBS labels and theirmeaning. Please help keeping this dictionary up to date by addingyour favorite labels. This table doesn’t dictate how to uselabels, but rather document how they are used. That said, obviouslyit will help everyone if we try to follow a common standard and usesimilar labels in the same way across all entities that useJBS.

Cloning the JDK

After the initial release of the JDK source code into OpenJDK in2007 the OpenJDK project moved from TeamWare to using Mercurial.Starting in 2019 the source revision control has been moved to Git.The complete source code for the JDK is today hosted atGitHub. You can browse the code directlyin theopenjdk/jdkrepository, or download the code for offline browsing, editing,and building usinggit clone.

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

openjdk/jdk is the mainline JDK developmentrepository where the next major release of the JDK is beingdeveloped. OtherProjects have their ownrepositories onGitHub.

If you intend to contribute patches, you should firstfork the repository onGitHub and clone your ownpersonalfork as shown below. To fork aProject onGitHub, go to the GitHub Project page andclick the ‘Fork’ button in the upper right corner, thenfollow 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 orSSH. These examples assume you have an SSH key installed onGitHub. If this is the first timeyou clone your personal fork of an OpenJDK repository you may wantto create an SSH key to use with it. SeeGenerating an SSH key below. Once youhave your personal fork and an SSH key to go with it, go ahead andclone.

$ git clone git@github.com:OpenDuke/jdk.git$ cd jdk$ git remote add upstream https://github.com/openjdk/jdk.git

In the example above Duke cloned his personal fork of the JDKmainline repository using SSH. You should of course use your ownGitHub username instead. Then, byadding a newremote named ‘upstream’, theclone is associated withopenjdk/jdk. Doing this willallow the tooling to automatically create a PR onopenjdk/jdk whenever a changeis pushed to the personal fork. The way that works is that once thechange has been pushed to the personal fork, and you navigate totheopenjdk/jdkrepository onGitHub, there willbe a message saying that you just pushed a change and asking if youwant to create a PR.

Working with git branches

It isstrongly recommended to always create anew branch for any change you intend to implement. If your PR getsaccepted, it will be squashed and pushed by the OpenJDK bots. Thismeans that if you make changes to yourmaster branch,it will diverge from the upstreammaster branch. Thisin turn means that your repo will forever be out of sync with theupstream repo, which will cause merge conflicts every single timeyou want to update your repo from upstream. Having a separatebranch for each change also means that you can easily work on manydifferent changes in parallel in the same code repository. Unlessyou know what you are doing, the recommendation is also to alwaysbase your new branch on themaster branch.

$ git switch -c JDK-8272373 master

Here we create a new branch calledJDK-8272373based on themaster branch and set the repository upto work in that new branch.

If you intend to work on a backport to a feature releasestabilization branch, your new local branch should of course bebased on the stabilization branch instead ofmaster.

$ git switch -c JDK-8272373 jdk23

git switch was introduced in Git version 2.23. Forearlier versions of Gitgit checkout can be usedinstead. However it is always recommended to use the latestversions of all your tools when possible.

Generating an SSH key

For security reasons you should always create new keys and usedifferent keys with each repository you clone. Thessh-keygen command generates an SSH key. The-t option determines which type of key to create.ed25519 is recommended.-C is used to adda comment in the key file, to help you remember which key it is.While it’s possible to use SSH without a passphrase, this isstrongly discouraged. Empty or insecurepassphrases may be reset usingssh-keygen -p; thisdoesn’t change the keys.

$ ssh-keygen -t ed25519 -C openjdk-jdk -f ~/.ssh/openjdk-jdkGenerating 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/openjdk-jdk.pub.The key fingerprint is:SHA256:WS4jCQMtat75ZEue+so+Lgj7V/sdMtj1FTNkfNsCfHA openjdk-jdkThe key's randomart image is:+--[ED25519 256]--+|  ..       ..oE  ||  ...       o+o .|| . .o     .  o+.o||..   o . +    .=.||o . . o S o   .. ||.. o +.+ + . .   ||o.  *.+.+ . .    ||o....=.  + .     || .=B=. .. .      |+----[SHA256]-----+

~/.ssh/openjdk-jdk is a text file containing yourprivate ssh key. There’s a corresponding public key in~/.ssh/openjdk-jdk.pub (as detailed in the exampleabove). You shouldnever share your private key.Thepublic key on the other hand should be uploaded toGitHub. Follow the steps below todo that.

• Go to the GitHub settings for your account by choosing“Settings” in the menu by your avatar in the upperright corner
• Go to “SSH and GPG keys”
• Click “New SSH key”
• Title “OpenJDK” (or something elseappropriate)
• Paste the content of~/.ssh/openjdk-jdk.pub intothe text field
  • To get the content of the file you can for instance usecat ~/.ssh/openjdk-jdk.pub
  • It will look something like this:ssh-ed25519AAAAC3NzaC1lZDI1NTE5AAAAIO8+egiIgWV+tE7LVVJmlR7WS2Lr3Fj7dXVo9HiasD6Topenjdk-jdk
• Click “Add SSH key”

Now you are ready to clone youropenjdk/jdk fork usingSSH.

Making a Change

In case you jumped directly here and skipped reading the earliersections of this guide, please keep in mind that there’s alot more to it than just making a change in the code and submit aPR to GitHub. The list below shows the bare minimum required beforea change can be accepted into OpenJDK.

1. Discuss the intended change – SeeContributing to anOpenJDK Project
2. Make sure an issue id exists for the work– SeeFiling an issue
3. Initiate a CSR request if your change have acompatibility impact – SeeWorking with the CSR
4. Fix the issue – SeeCloning the JDK,Working with git branches, andBuilding the JDK
5. Write regression tests and run relevant regression andunit tests on all relevant platforms – SeeTesting the JDK
6. Create a changeset – SeeWorking With Pull Requests
7. Update the bug content – SeeUpdating an issue whilefixing
8. Request a review of the changes – SeeLife of a PR
9. Merge with the latest upstream changes and testagain
10. Integrate the changeset – SeeWorking With Pull Requests
11. Write a release note if appropriate –SeeRelease Notes

Working with the CSR

Changes that have a compatibility impact will require a separateapproval besides the code review. This is handled through aCompatibilityand Specification Review, a.k.a. CSR. Compatibility impact canbe things like requiring a specification change, directly affect anexternal interface, changing command line options, or otherwisealter the behavior of the JDK in ways that could cause issues forusers when upgrading to the next JDK version.

See theCSRwiki for information on how to work through the CSRprocess.

The CSR must be approved before the change is allowed to beintegrated to a feature release or update release repository.Feature design and implementation work may begin concurrently withthe CSR review, but may need to be modified in response to CSRfeedback.

Copyright Headers

All source code files in OpenJDK has a header with copyrightstatements and a license. Since this is legal documentation itshall not be updated or modified without seeking guidance from yourlegal representative. For that reason this guide can’t reallygive detailed information on what you can or should do. There arehowever a few generic things that can be clarified.

This is an example copyright/license header:

/* * Copyright (c) 2018, 2021, Oracle and/or its affiliates. All rights reserved. * Copyright (c) 2018, 2020 SAP SE. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation. * * This code is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */

This header has two copyright notices at the top (Oracle and SAPSE) and below them the license text.

As stated in the header, don’t make changes to thecopyright notices or the license text below them. If youraffiliation has a copyright notice at the top of the header,consult your legal representative on how to update it. If youraffiliation doesn’t have a copyright notice, again consultyour legal representative to see if you should add one. Do notupdate a copyright notice if you don’t belong to thataffiliation unless explicitly asked by the affiliation inquestion.

If you create a new file, copy the license text from a nearbyfile. Do not add copyright notices for affiliations to which youdon’t belong.

If you move code from an existing file to a new file, bring theentire copyright + license header over to the new file.

Changes Late in theRelease

You should always aim to get your changes integrated as early ina release as possible to maximize the amount of testing done beforerelease. If you risk running late, it’s almost always abetter idea to defer the change to the next release rather thantrying to squeeze it in in the last minute. The next release isonly six months away, the world can wait even though you areeager.

Integrating during the rampdown phase is not recommended. Thebar to integrate a change in the rampdown phase is considerablyhigher than during the normal development phase. SeeThe JDK Release Process for moreinformation. Also note that changes that are made late in therelease shouldn’t expect localization since this in itselftakes some time.

Building the JDK

The JDK build system is a fairly complex machine that has theability to build anything from a single module to a completeshippable JDK bundle with various levels of debug capabilities, runtests, install your newly built JDK on your system, orcross-compile for some other system. The build usesmake and a few other tools that you will have toinstall on your system before starting.

The JDK supports incremental builds. This means that if you havea 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 partneeds to be rebuilt. So subsequent builds will be faster and youcan always use a make target that results in a complete JDK imagewithout having to worry about actually building the entire JDKevery time. Please note that the incremental build do have limitsin its understanding of what you change. For instance, if youchange behaviors or conventions in one module there may be otherparts of the JDK that implicitly depends on these withoutmake’s knowledge. For this reason you may have to rebuildseveral modules, or do a clean build if you change things that mayhave a wider impact.

The examples below show the steps taken to build the JDK sourcecode. Please seeCloning the JDK forinformation on how to download it. These examples were written inthe JDK 17 development time frame which is why the boot JDK usedhere is JDK 16. Note that the download links used here point to JDK16 bundles. To build JDK N, use JDK N-1 as the boot JDK.

The configure script will tell you what additional packages youneed. In this first example several packages were needed since thisbuild was performed on a clean Ubuntu installation. The configurescript was run several times to get all the dependencies, but onlythe commands actually needed to get the JDK built are included inthe log. This is just an example log, don’t copy theapt-get install line. Instead runsh./configure to see what packages you actually need on yoursystem.

$ wget https://download.java.net/java/GA/jdk16/7863447f0ab643c585b9bdebf67c69db/36/GPL/openjdk-16_linux-x64_bin.tar.gz$ 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 inbuild/linux-x86_64-server-release/jdk. The exact pathdepends on your build platform and selected configuration.

The second example is from a clean (newly installed) Mac runningMacOS Big Sur. Please note that in this case there are some stepstaken outside of the terminal. First XCode and the XCode commandline tools must be installed. It could be that the most recentversion of XCode that you get from App Store is too new to havebeen properly tested with the JDK build. Seethe JDK build instructions for supported versions and moredetails in case you need to install an older version of XCode. Inthis exampleMac Ports isused to installautoconf.autoconf canalso be installed usingHomebrew andsurely through other sources as well.

$ curl https://download.java.net/java/GA/jdk16.0.1/7147401fd7354114ac51ef3e1328291f/9/GPL/openjdk-16.0.1_osx-x64_bin.tar.gz --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 inbuild/macosx-x86_64-server-release/jdk.

Configuration options

The JDK build is extremely configurable. This list only containsthe most basic configure options needed to get you started. Useconfigure --help to see a complete list ofoptions.

Working with multipleconfigurations

Through the configure flags you will select what configurationof the JDK to build. The name of the output directory for the builddepends on this configuration. In the example above the JDK endedup inlinux-x86_64-server-release. This means that wemade a release build of a 64 bit linux x86 version of the serverJDK. If we change some of these options the output directory willbe affected accordingly.

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

In the example above we built arelease image. Tobuild a debug image as well we can configure with--with-debug-level=slowdebug. This will give us a JDKwhere for instance asserts in the JDK source code are enabled. Toselect which JDK to work with in later calls tomakeaddCONF=<configuration>.

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

Make targets

make images, as used in the example above, willbuild a JDK image which is very close to what you’d get fromany JDK provider. There are several other make targets you can usedepending on what you’re looking for. The table belowcontains some commonly used make targets.

There are many other targets available as well. Usemakehelp to find out more.

Testing the JDK

In addition to your own Java applications, OpenJDK has supportfor two test frameworks to test the JDK, jtreg and GTest. jtreg isa Java regression test framework that is used for most of the teststhat are included in the OpenJDK source repository. The Google Test(GTest) framework is intended for unit testing of the C++ nativecode. Currently only JVM testing is supported by the GTestframework. Other areas use jtreg for unit testing of C++ code.

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

Please note that what’s mentioned later in this section,likeGHA and tier 1 testing, willonly run a set of smoke-tests to ensure your change compiles andruns on a variety of platforms. They won’t do any targetedtesting on the particular code you have changed. You must alwaysmake sure your change works as expected before integrating, usingtargeted testing. In general all changes should come with aregression test, so if you’re writing product code you shouldalso be writing test code. Including the new tests (in the rightplaces) in your change will ensure your tests will be run as partof your testing on all platforms and in the future.

A few key items to think about when writing a regressiontest:

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

The jtreg documentation has a section onhow to write good jtregtests.

There are a few examples where it doesn’t make sense towrite an explicit regression test. These should be tagged in JBSwith one of thenoreg-labels.

jtreg

In-depth documentation about the jtreg framework is found here:jtreg harness. jtregitself is available in theCode ToolsProject.

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

/* * @test * @summary Make sure feature X handles Y correctly * @run main TestXY */publicclass TestXY{publicstaticvoidmain(String[] args)throwsException{        var result= X.y();if(result!= expected_result){thrownewRuntimeException("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 casewe simply tell jtreg to execute the main method of the classTestXY.@run isn’t strictlynecessary for jtreg to execute the test, an implicit@run tag will be added if none exists. However, forclarity and in order to avoid bugs it’s recommended to alwaysexplicitly 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 thatthis test is a regression test for. The bug id is written withouttheJDK- prefix.

@bug 8272373

You can add several bug ids in the same@bug tag,separated by a single space. These bug ids refer to product bugsfor which a fix is verified by this test. JBS issues that trackchanges to the test itself are not listed here.

You can also specify a number of requirements that must befulfilled for jtreg to execute the test.

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

And you can specify if the test requires specific modules, orcommand line flags to 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 thesame 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 filterthe test selection. For instance if you have a UI test which needsto display a window you’ll want to make sure the test harnessdoesn’t try to run this test on a system which doesn’tsupport headful tests. You do this by specifying

@key headful

Another example is@key randomness that should beused to indicate that a test is using randomness - i.e. isintentionally non-deterministic.

There are many other keywords in use and their usage may differbetween areas in the JDK. Make sure you understand the conventionsfor the particular area you are testing since these are justexamples.

Thejtreg documentationprovides information on many more tags like these.

Thecompilergroup has a section in their wiki withGuidelines for“langtools” tests.

Running OpenJDK jtregtests

When configuring the OpenJDK build you can tell it where yourjtreg installation is located. When providing this information youcan later runmake run-test to execute jtregtests.

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

In the OpenJDK source tree you can find a directory calledtest. There are a large number of tests in thisdirectory 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 caseyou’ll need to tell jtreg which JDK to test.

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

GTest

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

staticintdemo_comparator(int a,int b){if(a== b){return0;}if(a< b){return-1;}return1;}TEST(Demo, quicksort){int test_array[]={7,1,5,3,6,9,8,2,4,0};int expected_array[]={0,1,2,3,4,5,6,7,8,9};  QuickSort::sort(test_array,10, demo_comparator,false);for(int i=0; i<10; i++){ASSERT_EQ(expected_array[i], test_array[i]);}}

ASSERT_EQ is one example of an assertion that canbe used in the test. Below are a few other examples. A full list isfound in theGoogleTest Documentation.

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

ASSERT is a fatal assertion and will interruptexecution of the current sub-routine.EXPECT is anonfatal assertion and will report the error but continues to runthe test. All assertions have both anASSERT and anEXPECT variant.

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

Running OpenJDK GTests

When configuring the OpenJDK build you can tell it where yourGTest installation is located. Once configured, use make to runGTests.

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

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

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 isone of client, server, etc.

GitHub actions

GitHub has a feature calledGitHub actions (GHA) that can be used to automatetesting. The GHA is executed whenever a push is made to a branch inyour repository. The bots will show the results of the GHA in yourPR when you create or update it. The GHA in the JDK Project isconfigured to run a set of tests that is commonly known astier 1. This is a relatively fast, small set oftests that tries to verify that your change didn’t break theJDK completely. In tier 1 the JDK is built on a small set ofplatforms including (but not necessarily limited to) Linux,Windows, and MacOS, and a few tests are executed using thesebuilds. There’s also a set of other platforms for which GHAdoes cross-complilation builds.

In addition to the testing you run manually before publishingyour changes, it’s recommended that you take advantage ofthis automated testing that the GHA offers. This will for instanceallow you to run tests on platforms that you may not otherwise haveaccess to. To enable this on your personal fork of the JDK onGitHub 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 linkto the actual file that describes them right below the greenbutton.

In case of failures in the GHA it’s always a good start totry to reproduce the failure locally on a machine where you havebetter control and easier access to a debug environment. There havebeen cases where the GHA has failed due to issues unrelated to thechange being tested, e.g. because the GHA environment wasupdated and changes were needed to the JDK GHA configuration. Theconfiguration is in general updated fairly quickly, so in caseswere you can’t reproduce the failure locally, considerre-running the GHA later.

Please keep in mind that the tier 1 tests run by the GHA shouldonly be seen as a smoke test that finds the most criticalbreakages, like build errors or if the JDK is DOA. These tests cannever replace the targeted testing that you always must do on yourchanges. There are several areas of the JDK that aren’t partof tier 1 at all. To see exactly what tier 1 includes, please seethe various TEST.groups files that you will find in thesubdirectories ofjdk/test/.

Excluding a test

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

Remember to remove the JBS id from the ProblemList or the testwhen the bug is closed. This is especially easy to forget if a bugis closed asDuplicate orWon’t Fix. jcheck will reportan error and prohibit an integration if a PR is created for anissue that is found in a ProblemList if the fix doesn’tremove the bug ID from the ProblemList.

ProblemListing jtreg tests

ProblemListing should be used for a short term exclusion while atest is being fixed, and for the exclusion of intermittentlyfailing tests that cause too much noise, but can still be useful torun on an ad-hoc basis. ProblemListing is done in the fileProblemList.txt. For more details about theProblemList.txt file see thejtreg FAQ.

There are actually several ProblemList files to choose from inthe JDK. Their location and name hint about what area or featureeach file belongs to. Each file has sections for differentcomponents. All ProblemList files complement each other to buildthe total set of tests to exclude in jtreg runs.

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

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

foo/bar/MyTest.java                        4711   windows-all

In this example,MyTest.java is ProblemListed onwindows, tracked by bugJDK-4711.

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

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

This would lead tosun.tools.jcmd.MyTest.java beingProblemListed only onwindows-all. The proper way towrite this is:

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

Althoughwindows-all isn’t strictly requiredin this example, it’s preferable to specify platforms foreach bugid (unless they are allgeneric-all), thismakes it easier to remove one of the bugs from the list.

A common way to handle the JBS issue used to problemlist a testis to create aSub-task of the bugthat needs to be fixed to be able to remove the test from theproblem list again.

Remember to always add aproblemlist label in the JBS issue referenced inthe ProblemList entry. When the issue is fixed, theproblemlist label can be removed from the JBSissue.

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

Some tests contain several test cases and there may be a need toProblemList 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 isspecified each test case can be referenced withid +ordinary number of the test case in the test file.

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

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

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

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

Due to an issue described inCODETOOLS-7902712tests that contains more than one@test must actuallyuse this way to specify all test cases if all of them should beProblemListed. Specifying just the test name will not work.

Running ProblemListedtests

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

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

Exclude jtreg tests using@ignore

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

/***@test*@ignore4711*/

In this example,MyTest.java is excluded, trackedby bugJDK-4711.@ignore should generallybe placed directly before the first “action” tag(e.g. @compile,@run) if any in thetest.

Dealing with JBSbugs for test exclusion

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

• Code review: ProblemListing a test isconsidered atrivial change.
• JBS issue: A JBS issue is obviously createdfor the bug that caused the failure, we call this themainissue. To exclude the test, create a subtask to the mainissue. Also add the labelproblemlist to the main issue.

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

Triage excluded issues

After a failure is handled by excluding a test, the main JBSissue should be re-triaged and possibly given a new priority. Thisshould be handled by the standard triage process. A test exclusionresults in an outage in our testing. This outage should be takeninto consideration when triaging, in addition to the impact of thebug itself.

Backing out a change

If a change causes a regression that can’t be fixed withinreasonable time, the best way to handle the regression can be toback out the change. Backing out means that the inverse(anti-delta) of the change is integrated to effectively undo thechange in the repository. Whether to back out a change or not willalways be a judgement call. How noisy and frequent are the failurescaused by the broken change? How soon can the fix be expected? Ifyou want to avoid having your change backed out, you should makesure to let the relevant developers know that you are working onthe fix and give an estimated ETA of the fix.

It will happen of course when the build is broken or the JDK isDOA and similar situations that a change is immediately backed outwithout further investigation. Backing out a change is howeverseldom the first course of action if the change has been done inaccordance with the guidance inWorking With Pull Requests. If,when investigated, it is found that a change didn’t gothrough relevant testing or there are other issues that should havebeen caught before integration if proper procedure had beenfollowed, it’s quite possible that a change is backed outeven if the author is desperately working on a fix. The JDK sourcecode is deliberately menat to have a high bar for acceptance ofchanges. If something crawls in underneath that bar it should mostlikely be backed out.

The backout is a regular change and will have to go through thestandard code review process, but is considered atrivial change. The rationale is that a backout isusually urgent in nature and the change itself is automaticallygenerated. In areas where two reviewers are normally required, onlyoneReviewer isrequired for a backout since the person who is performing thebackout also should review the change.

There are two parts to this task, how to do the bookkeeping inJBS, and how to do the actual backout in git.

How towork with JBS when a change is backed out

1. Close the original (failed) JBS issue(O).
   • “Verify” the issue and choose “FixFailed”.
2. If the intention is to fix the change and submit it again,create a redo-issue(R) to track that the workstill needs to be done.
   • Clone(O) and add the prefix[REDO] on the summary - the clone becomes theredo-issue(R).
   • Make sure relevant information is brought to(R).
   • Remember that comments aren’t automatically brought overwhen cloning.
3. Create a backout-issue(B):
   • Alternative 1 - the regression is identified directly.
     • Create a sub-task to(R) with the same summaryprefixed with[BACKOUT].
   • Alternative 2 - an investigation issue was created(I), and during the investigation backing out thechange is identified as the best solution.
     • Use the investigation issue(I) for thebackout.
     • Change summary of(I) to the same as(O) and prefix with[BACKOUT].
     • Move and change type of(I) to become asub-task of(R).
   • Alternative 3 - no redo issue was created.
     • Create a backout-issue(B) with the samesummary as(O), prefix with[BACKOUT].
     • Add arelates to link between(B) and(O).
4. If(O) had a CSR request, update the CSR issueas follows:
   • Add a csr-for link from the CSR to(R).
   • Add a note to the CSR that explains the reason for the redo andthe impact on the CSR.
   • Move the CSR back into the Finalized state for re-review.(It’s necessary to first move the CSR back to the Draft statebefore moving it to the Finalized state.)

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

How towork with git when a change is backed out

To backout a change with git, usegit revert. Thiswill apply (commit) the anti-delta of the change. Then proceed asusual with creating a PR and getting it reviewed.

$ git show aa371b4f02c2f809eb9cd3e52aa12b639bed1ef5commit aa371b4f02c2f809eb9cd3e52aa12b639bed1ef5 (HEAD -> master)Author: Jesper Wilhelmsson <jesper.wilhelmsson@oracle.com>Date:   Wed Jun 23 20:31:32 2021 +0200    8272373: Make the JDK mine    Reviewed-by: dukediff --git a/README.md b/README.mdindex 399e7cc311f..4961acb2126 100644--- a/README.md+++ b/README.md@@ -1,4 +1,4 @@-# Welcome to the JDK!+# Welcome to my modified JDK! For build instructions please see the [online documentation](https://openjdk.org/groups/build/doc/building.html),$ git revert aa371b4f02c2f809eb9cd3e52aa12b639bed1ef5[master d454489052d] 8280996: [BACKOUT] Make the JDK mine Reviewed-by: duke 1 file changed, 1 insertion(+), 1 deletion(-)$ git show d454489052dc6ff69a21ad9c8f56b67fdeb435eecommit d454489052dc6ff69a21ad9c8f56b67fdeb435ee (HEAD -> master)Author: Jesper Wilhelmsson <jesper.wilhelmsson@oracle.com>Date:   Wed Jun 23 20:32:08 2021 +0200    8280996: [BACKOUT] Make the JDK mine    Reviewed-by: dukediff --git a/README.md b/README.mdindex 4961acb2126..399e7cc311f 100644--- a/README.md+++ b/README.md@@ -1,4 +1,4 @@-# Welcome to my modified JDK!+# Welcome to the JDK! For build instructions please see the [online documentation](https://openjdk.org/groups/build/doc/building.html),

Backing out a backport

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

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

1. Close the original (failed) JBS backport issue(O).
   • “Verify” the issue and choose “FixFailed”.
2. If the intention is to fix the backport and submit it again,create a redo-issue(R) to track that the workstill needs to be done.
   • Clone(M) and add the prefix[REDOBACKPORT] on the summary - the clone becomes the redo-issue(R).
   • Add arelates to link between(R) and(O).
   • Set Fix Version of(R) to the target releasefor the backport - either the exact release if known, or<N>-pool if it’s not critical whichrelease 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 samesummary, but prefixed with[BACKOUT BACKPORT].
   • Alternative 2 - an investigation issue was created(I), and during the investigation backing out thebackport is identified as the best solution.
     • Use the investigation issue(I) for thebackout.
     • Change summary of(I) to the same as(M) and prefix with[BACKOUTBACKPORT].
     • Move and change type of(I) to become asub-task of(R).
   • Alternative 3 - no redo issue was created.
     • Create a backout-issue(B) with the samesummary as(M) and prefix with[BACKOUTBACKPORT].
     • Add arelates 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 abackport

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

Rationale for using thismodel

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

• Abackported by link should only refer to issues oftype Backport
• A bug id should never be reused for different patches in thesame repository

Disadvantages of this model are that the list of backports inJBS will still list the old (failed) backport as the 15.0.2backport, and the new backport will not be linked to using abackported by link. It is assumed that the advantagesabove outweighs the disadvantages and that the capital letterprefixes for the backout and the redo will be visible enough in JBSto alert that something fishy is going on.

Working With Pull Requests

Once you have made a change that you want to integrate into anOpenJDK code base you need to create aPull Request (PR)onGitHub. This section assumesthat you have previous experience from using git andGitHub, and won’t go into details ofhow those work. Still, the aim is of course to provide a usefulguide, sosend an email if moredetails are needed.

This section also assumes that you have already readI have a patch, what do I do?and followedall the steps there.

Think once more

All code reviews in OpenJDK are done in public. Once you openyour PR for public review the internet can see it and comment onit. Make sure your code is ready for it. Look through yourcomments, make sure that temporary code is gone, and make sure youhave sanitized your method and variable names. Also, make sure youunderstand your code. Why is it working? What are the potentialpitfalls? What are the edge-cases? If you haven’t alreadyanswered all these questions in the mail conversation that precededthis PR, it’s likely that you will need to answer them duringthe review.

It’s also worth taking the extra time to see if the changecan be split into a few different separate changes. A large changewill take more effort and thus attract fewerReviewers. Smallerchanges will get reviewed faster and get better quality reviews.You can compare proposing a single large change to proposing tenindividual small unrelated changes. What happens in practice whenall these ten changes are presented as one PR is that there’sa focus on say 5-6 of these smaller changes and no one really lookshard at the other 4-5. For complexity, even small changes that arehard to understand and test may be risky.

The timing of your change will also affect the availability ofreviewers. The JDK runs on asix-monthsrelease cadence. During the months around the start of the rampdown phase most area experts will be busy working on their ownchanges and reviewing major features that are planned for therelease. If you propose a change during this period (basicallyMay-June, or November-December) it may take a long time before youget the required reviews.

Rebase before creating thePR

It’s likely that other people have integrated changes tothe code base since you created your branch. Make sure to pull thelatest changes and rebase your fix on top of that before creatingyour PR. This is a courtesy issue. Your reviewers shouldn’thave to read your patch on top of old code that has since changed.This is hopefully obvious in cases where the upstream code has gonethrough cleanups or refactorings, and your patch may need similarcleanups in order to even compile. But even in cases where onlysmaller changes have been done, the reviewers shouldn’t haveto react to issues like “that line of code was moved lastweek, why is it back there?”.

Most changes are made to themaster branch of themainline repository. In these cases, rebase using:

git rebase master

Note that if you are working on a backport to a stabilizationbranch you should replacemaster above with the nameof the branch you are targeting. This would be the same name aswhen you cloned the branch.

After the PR has been published, rebasing, force-pushing, andsimilar actions are strongly discouraged. Such actions will disruptthe workflow for reviewers who fetch the PR branch. Pushing newchanges is fine (and even merging if necessary) for a PR underreview. Incremental diffs and other tools will help your reviewerssee what you have changed. In the end, all commits will be squashedinto a single commit automatically, so there’re actually nodrawbacks whatsoever to making commits to a PR branch duringreview.

Final check beforecreating the PR

Creating the PR is essentially the same as asking a large groupof people to start reviewing your change. Before doing that, youwant to make sure your change is done in every detail you have thepower to control. These are a few of the things you should thinkabout in order to avoid wasting people’s time on anunfinished change. (You may think that some of these are tooobvious to even mention, but all of them are things that in thepast have caused actual failures that broke the JDK forall developers out there.)

• Is the copyright statement at the top of each modified sourcefile correct?

• Did you run a full build and all relevant tests on thefinal version of the change? It’s importantto do this on the truly final version, as even an apparentlytrivial change in a comment can break the build.

• Did yougit add all new files?

• Did you add regression tests for your change?

• Did you run those new regression tests?

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

If you have an actual reason to create a PR before the change isall done, make sure to create it inDRAFT mode. Thebot won’t add therfr label or send emails tolabeledGroups aslong as the PR is inDRAFT mode.

Life of a PR

1. Make sure the PR is reviewable

   There are changes that span across several areas, for examplewide spread cleanups or the introduction of a new language feature.Accordingly, the number of lines of code touched can be quitelarge, which makes it harder to review the entire PR. In suchcases, it may make sense to split the change into several PRs, mostcommonly by grouping them by module or area.

2. Make sure you target the correct branch

   Many project repositories have several branches. Make sure yourPR targets the correct one. This is of course especially importantwhen not targeting the default branch. At the top of your PR, rightbelow the title, it will say “NNN wants to merge X commit(s)into [branch]”. A typical red flag to watch out for is ifyour PR seems to include commits or changed files thatshouldn’t be part of your integration. E.g. Seeing the“Start of release updates for JDK N” when backportingsomething to JDK N-1 is a bad sign.

3. Set a correctly formatted title

   The title of the PR should be of the form “nnnnnnn:Title of JBS issue” wherennnnnnn is theJBS issue id of the main JBS issue that is being fixed, and theTitle of JBS issue is the exact title of the issue aswritten in JBS. In fact, the title can be set toonly theJBS issue id (nnnnnnn) in which case the bot willfetch the title from JBS automatically. If you are creating abackport PR, seeUsing the Skaratooling to help with backports for more details on the titlerequirements.

4. Write a useful description

   The description of the PR should state what problem is beingsolved and shortly describe how it’s solved. The PRdescription should also list what testing has been done.Reviewers and otherinterested readers are referred to the text in the JBS issue fordetails, 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 tolists with many receivers, so a too long description can cause alot of noise, while of course a too short description won’tgive the reader enough information to perform the review. If youhave a lot of information you wish to add to your PR, likeperformance evaluations, you can put that in a separate comment inthe PR.

5. Finish the change before publishing it

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

6. Make sure all relevantGroups areincluded

   The bot will make an attempt to include theGroups that need to reviewyour change based on the location of the source code you havechanged. There may be aspects of your change that are relevant tootherGroups aswell, and the mapping from source toGroups isn’t alwaysperfect, so make sure all relevantGroups have been included,and add new labels using/label if needed. Consult theCode Owners section if you are unsure of whoowns the code you are changing.

7. Allow enough time for review

   In general all PRs should be open for at least 24 hours to allowfor reviewers in all time zones to get a chance to see it. It mayactually happen that even 24 hours isn’t enough. Take intoaccount weekends, holidays, and vacation times throughout the worldand you’ll realize that a change that requires more than justa trivial review may have to be open for a while. In some areastrivial changes are allowed to beintegrated without the 24 hour delay. Ask your reviewers if youthink this applies to your change.

8. Get the required reviews

   At least oneReviewer knowledgeable ineach area being changed must approve every change. A change maytherefore require multipleReviewers because itaffects multiple areas. Some areas (e.g. Client and HotSpot)require two reviewers in most cases, so be sure to read therelevantOpenJDKGroup pages for advice or ask yourSponsor.

   Be open to comments and polite in replies. Remember that thereviewer wants to improve the world just as much as you do, only ina slightly different way. If you don’t understand somecomment, ask the reviewer to clarify. Accept authority whenapplicable. If you’re making changes in an area whereyou’re not the area expert, acknowledge that your reviewersmay be. Take their advice seriously, even if it is to not make thechange. There are many reasonswhy a change may get rejected. Andyou did read the sectionThingsto consider before proposing changes to OpenJDK code,right?

9. 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 PRbranch. The PR will be updated automatically. Multiple commits tothe branch will be squashed into a single commit when the PR iseventually integrated.

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

   If you want to update the title of the PR, remember that the oneand only truth is the JBS issue, so the title must first be changedthere.

   After having made all updates needed to get to the final versionof the change, remember to re-run relevant testing. Even minorchanges may go bad and you don’t want to cause (another)build failure due to an updated comment.

10. Merge the latest changes

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

    If your PR is targeting some other branch thanmaster, make sure to merge the correct upstream branch(the target branch). Verify that your PR doesn’t includechanges from some other branch (e.g. master) thataren’t supposed to be there.

    If there are upstream changes that might affect your change,it’s likely a good idea to rerun relevant testing as well.TheGHA testing that’s doneautomatically byGitHub shouldonly be seen as a smoke test that finds the most severe problemswith your change. It’s highly unlikely that it will test youractual change in any greater detail - or even at all execute thecode that you have changed in most cases.

11. Integrate your change

    When you have the required reviews and have made sure allrelevant areas have had a chance to look at your change, integrateby entering the command/integrate in a comment on the PR. If you are notyet aCommitterin theProject,ask yourSponsorto enter the command/sponsor in the PR as well in order for yourchange to be allowed to be integrated.

12. After integration

    After you have integrated your change you are expected to stayaround in case there are any issues with it. As mentioned above,you are expected to have run all relevant testing on your changebefore integrating your PR, but regardless of how thorough you testit, things might slip through. After your change has beenintegrated an automatic pipeline of tests is triggered and yourchange will be tested on a variety of platforms and in a variety ofdifferent modes that the JDK can be executed in. A change thatcauses failures in this testing may be backed out if a fixcan’t be provided fast enough, or if the developerisn’t responsive when noticed about the failure. Note thatthis directive should be interpreted as “it’s a reallybad idea to integrate a change the last thing you do beforebedtime, or the day before going on vacation”.

Webrevs

As allOpenJDKProjects are hosted onGitHub,most code reviews takes place there. When you publish a PR to anOpenJDK repository the corresponding JBS issue will get a link tothe code review in the PR, making this the natural place to go forreview. OpenJDK do however provide other tools and infrastructurefor code reviews as well: Thewebrevs.

Webrev refers to both the tool used to create them and itsoutput. The script,webrev.ksh,is maintained in theCode ToolsProject. Please note that this version of webrev is for usewith mercurial and won’t work with the git basedrepositories. You don’t actually need tools like this anymoreunless you want to host code reviews in other locations thanGitHub.

On the GitHub reviews you will find links to webrevs. These areautomatically generated by the bot and are provided as a complementfor those who prefer this style of code review. Many OpenJDKdevelopers are used to the webrevs as this was the default way toprovide code for review before OpenJDK moved toGitHub. Though webrevs are mainlydeprecated today, they used to be a central part of OpenJDKdevelopment and you may still see people use the word as a synonymfor code review, so they do deserve to be mentioned here aswell.

Filestorage for OpenJDK artifacts -cr.openjdk.org

Thecr.openjdk.org server provides storage anddisplay of code review materials such as webrevs and otherartifacts related to the OpenJDK Community. This area can also beused to store design documents and other documentation relatedOpenJDK but not related to any specificProject that have anOpenJDK wiki space for such purposes.

Any OpenJDKAuthor can publishmaterials on thecr.openjdk.org server. Users canupload files to temporary storage using secure methods(rsync,scp, andsftp).

This site is for open source materials related to the OpenJDKCommunity only. Users uploading inappropriate materials will loseaccess and the material will be deleted. Please review theTerms of Use beforeusing this server.

Get your SSH key installed

To usecr.openjdk.org you’ll need to get anSSH key installed. SeeGeneratingan SSH key for guidance on how to generate a key. Your publickey (~/.ssh/id_rsa.pub) should be mailed as anattachment along with your JDK username tokeys@openjdk.org. An administratorwill install your key on the server and notify you on completion.This process may take a couple of days.

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

Reviewing and Sponsoringa Change

Two of the most important contributions you can make in theOpenJDK community are to review and sponsor changes for otherdevelopers. All changes needs to be reviewed. Many changes evenneed to be reviewed by more than one person. This means that inorder to enable a fast-pased development experience, all developersneed to review more changes then they produce themself.

If you are new to an area, reviewing changes is also a great wayto learn the code and see what general styles and types of changesare relevant in the area. Be mindful though, if you don’tknow the area well you should state this in your reviewcomments.

New developers in the OpenJDK community don’t have thepermissions needed to integrate changes to the repositories. Thisis a feature that ensures that all developers get familiar with thecode, processes, and community before being allowed to actuallymake changes. To get their first changes in, the new Contributorneeds the help of a Sponsor. The Sponsor’s role is to offerconstructive advice and eventually integrate the sponsoredcontribution into the repository.

Sponsoring new contributions is an important activity -it’s how the engineering culture of a project gets passed onfrom the core group to new Contributors, from one generation to thenext. Take pride in the value you provide to Contributors. Theirsuccess reflects well on you.

There are many different reasons to sponsor a change anddepending on the situation the exact steps involved may differsignificantly. An experienced developer hired into a larger team ofOpenJDK developers is likely to get much of the requiredinformation by osmosis and will likely need less help from asponsor than the enthusiast sitting at home with no priorexperience of large scale software development. This text aims tohighlight the steps involved in sponsoring a change but can’tcover all possible scenarios. As always, common sense takesprecedence where the assumptions made here doesn’t apply toyour use case.

Responsibilities of aReviewer

As aRevieweryou have a responsibility to make sure changes are sound and alignwith the general direction of the area. If you, as aReviever, review a changein an area that you don’t know well you probablyshouldn’t be the one to approve the change.

Reviewersshould be aware that they take full responsibility for theappropriateness and correctness of any changes in their area ofexpertise. If something goes wrong (e.g., the build breaks) and thechange’s author is unavailable, they may be asked to dealwith the problem. PotentialReviewers are encouragedto refuse to review code for which they aren’t qualified.

Reviewersshould examine not only the code being added or changed but alsothe relevant unit or regression tests. If no tests are being addedfor a change that isn’t already covered by existing tests andhave the appropriatenoreg- label,theReviewershould question this.

As aReviewer,Contributors will look up to you for guidance to get theircontributions into the project - your actions will determinewhether Contributors will feel welcome and want to engage furtherwith the project beyond their initial attempt, or not. Let’snot lose enthusiastic, engaged and technically competentContributors due to a lack of communication. If you see a requestin your area of expertise and you can’t address it, at leastacknowledge receipt of the request and provide an estimate for whenyou’ll be able to give it your attention. A frank explanationof your time constraints or commitments will be appreciated andrespected.

Reviewing a change onGitHub

Code reviews in OpenJDK happens onGitHub. This guide will hint atthe most common steps to perform a review but it’s not acomplete documentation of all features. For official documentationsee theGitHub Docs.

When you arrive at a pull request there are a few differentsections that you can browse through, Conversation, Commits,Checks, and Files changed. We will look at the first and the lastof these.

Conversation

The Conversation section is where all discussion around the PRhappens. Note that this section is intended for technicaldiscussion around the actual implementation of a change. This is ingeneral not the place to discuss the appropriateness of the changeor have overarching design discussions, that should happen on theappropriatemailing lists. Yes, PRcomments will be sent to the mailing lists as well, but it’sunlikely that all the right people will see it. PR mails sent tothe mailing lists will have a subject indicating that it’sabout the specific implementation in the PR. If the discussion islarger than just about the specific implementation, for instancearound the design or future of the feature, then a much largeraudience needs to be made aware of the discussion. A separate emailthread with a proper subject is preferred in such cases.

You can either reply to existing comments by using the textfield beneath each comment, or add a new comment by scrolling tothe bottom of the page and use the larger text field where it says“Leave a comment”.

Reviews take time for everyone involved. Your opinions are muchappreciated as long as they are on-topic and of a constructivenature. A comment of the form “I don’t like this”won’t help anyone to improve the change. Instead express whatit is that you don’t like and give examples of how to do itdifferently. Always be polite and make sure you read through allprevious comments before adding your own, the answer you arelooking for may already have been given.

Never ask the author of a change to fix unrelated issues in thecode that you find during your review. Such issues should behandled through a separate JBS issue and PR.

Files changed

The Files changed-section is where the actual change ispresented. On the left hand side there’s a list of all fileschanged. This is useful to get a quick overview and to see if thechange touches an area that you need to review.

The diff view is pretty straight forward, red stuff has beenremoved, green stuff has been added. You can configure (among otherthings) if you want a unified diff or a split view, if you want tohide whitespace changes, what types of files you want to show, andif you want to show the entire change or just what’s happenedsince your last review.

When you hover the text in the change a blue square with a plussign pops up to the left of the line. Click it to add a commentabout the change on the corresponding line. When you create yourfirst comment you have the option to simply add a single comment orto start a review. In general you want to start a review so thatall your comments are gathered in the same context when emails aresent out etc. You can also attach a comment to a file rather thanto a specific line in the file by using the speech bubble icon atthe top right.

When a complete file has been reviewed there’s a“viewed” checkbox at the top right that can be used tohide the files that you are done with. This is useful for changesthat involve many files.

Once you have looked through all the changes and added all yourcomments, the green button at the top right of the screen“Review changes” is used to finish your review. You canadd a final comment to sum up your findings and then choose whetheryou just want to provide your comments, if you want to approve thechanges, or request that changes are done before the change can beapproved. Finally click “Submit review” to publish yourthoughts.

Trivial changes

A change that is small, well contained, and that makes nosemantic changes can be calledtrivial. Typical examplesare fixing obvious typos or renaming a local identifier. A trivialchange can also be integrating an already-reviewed change that wasmissed in an earlier integration (e.g., forgot to add a file) orgenerated changes like agitrevert. It’s up to the author of a change to claimthat the change is trivial in the RFR, and it’s up to theReviewer whetherto approve such a claim. A change is trivial only if theReviewer agrees that itis. A trivial change doesn’t need to wait 24 hours beforebeing pushed, and it only needs oneReviewer, even in areaswhere stricter rules for integration normally apply.

Volunteering tosponsor a contribution

In an ideal situation opportunities to sponsor contributionsoccur in the OpenJDK mail lists. Since Contributors are encouragedto discuss their intended changes before they submit a patch, theideal time to declare your sponsorship is during that initialconversation. As a Sponsor you should offer advice and collaboratewith the Contributor as necessary to produce a high-quality patch.In addition to sponsoring changes to code you regularly maintain,there may be other areas where you can serve as a Sponsor.

After publicly committing to sponsoring a contribution, you needto “claim the sponsorship request” inJBS unless the Contributor already hasa JBS account and can assign the bug to themself. To do that youneed to perform three steps:

• Assign the bug to yourself.
• Add a comment providing the name of the Contributor and asummary of the approach to solving the problem.
• Set the bug’sStatus toIn Progress.

If the contribution doesn’t already have an associatedOpenJDK bug then create one inJBS.

It should be noted that claiming the sponsorship can take manyother forms. In cases where a change has been discussed, or astarter bug has been picked up and fixed even though a sponsorhasn’t been identified yet it may be as simple as justshowing up at the PR and sponsor the change once it’s beenreviewed.

Responsibilities of asponsor

As a sponsor, you aren’t technically required to reviewthe change, other Reviewers may already have looked at it or signedup to review. But it will be your name on the commit so you shoulddo whatever you feel is needed to be comfortable with that. You mayneed to work with the Contributor to make any necessary changes,until you and the Contributor are satisfied with the result, andyou are satisfied that the proposed contribution will pass anyrelevant review and testing. That may take more than one iterationin the worst case. You may also need to help out with any processor practical questions around the OCA, GitHub PRs, and specificrequirements in the area or project.

To integrate the change the Contributor should use the command/integrate on the PR as prompted by the bots. Oncethat is done, you as a sponsor enter the command/sponsor in a comment on the PR.

Once the change has been integrated you may need to keep an eyeout for any reported test failures and be prepared to investigateif such failures stem from the change you sponsored, and if so,work with the Contributor to resolve the issue.

Backporting

Development of the latest version of the JDK often results inbug fixes that might be interesting to include in some of the JDKUpdate releases still being maintained or in a feature releasestabilization branch. Moving a fix from a more recent release train(e.g. JDK 21) to an older release train (e.g. JDK 17) iscalledbackporting.

The guideline for what to backport into a specific release willvary over the lifetime of that release. Initially more fixes areexpected to be backported as new features and large changesintroduced in a mainline release stabilize. Over time the focuswill shift from stabilization to keeping it stable - the releasewill go into maintenance mode. This means that bug fixes thatrequire larger disruptive changes are more likely to be made inmainline and backported to more recent release trains only, and notto older release trains.

Over time it’s likely that the code base will divergebetween mainline and any given update release, and the cost ofbackporting will increase. The cost in this case is not only theeffort needed to perform the actual backport, but also the costinferred by bugs introduced by the backport. This should be takeninto consideration when deciding if a change should be backportedor not. For more details on how to reason around what to backport,this email from JDK 8 Updates Project lead Andrew Haley hassome guidelines for JDK 8u. The reasoning in this mail is specificto JDK 8u, but will in general apply to any JDK release inmaintenance mode.

Any change that originally required a CSR will require a new CSRto be backported unless the backport was covered by the initialCSR. Changes to Java SE specifications cannot be made in an updaterelease without a Java SE Maintenance Release. CSR-related issuesaffect interfaces and behavior and must be very carefullyscrutinized.

Backporting to a feature release stabilization branch

During ramp down of a feature release there are two branches ofthe mainline repository in play, the release stabilization branchfor the outgoing release, and themaster branch wherethe next release is being developed. Any change going into therelease stabilization branch is likely to be desired inmaster as well. When making a change intended for boththe stabilization branch andmaster, you should alwayscreate your pull request targetingmaster first, andthen, once the pull request is integrated, backport the resultingcommit to the release stabilization branch. For bug fixes that areonly applicable to the release stabilizationbranch, regular pull requests targeting the stabilization branchshould be created.

Please note that special rules applies during ramp downregarding what can and can’t be included into thestabilization branch. See theThe JDK Release Process for moreinformation.

Backporting multiplerelated changes

Ideally fixes should not be backported until there has beenenough time for any regressions or follow-on issues to have beenidentified. Then, when looking to backport a fix the developershould look for bothblocked by andcauses links in order to understandthe complete set of fixes that should be backported.

When backporting a number of changes that are dependent on eachother, like a change with a tail of bug fixes, it can sometimesseem attractive to merge all those commits into a single change toavoid backporting a broken change. Please don’t. The generalrecommendation is to backport each commit individually. There areseveral reasons for this recommendation.

If, for instance, there are other changes between the originalone and the followup fix(es) there may be a dependency on otherchanges that are unrelated to the issue itself. By merging theoriginal change, the fix(es), and the unrelated changes to meet thedependency, a single very different change is created. It’sunlikely that this change will match the description in the singleJBS issue used for the merged backport. Backporting each commitindividually will preserve the git history and make it easy tofigure out what has actually been backported.

Testing each individual change is more likely to find issuesthan just testing the single merged change. It’s also easierand less error prone to use the/backport command oneach commit instead of manually cherrypick and deal with the mergesetc.

And finally, if backporting each commit individually, the JBSrecords will clearly indicate that the followup changes have beenbackported as well. This is important as there is tooling thatverifies that everything is done in the right way. That toolingwill be confused if it can’t deduct from JBS what hashappened.

Working with backports inJBS

Example of backport hierarchy

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

There can be cases where it’s desirable to create abackport issue before the fix is done, e.g. if a CSR needs tobe filed. In these cases set theFixVersion/s of the backport toN orN-pool, whereN is the release train thebackport is targeting. E.g.17-pool. Please note thateven if a backport issue is created ahead of time, all work done inJBS for approvals and similar is still done in the main issue.

Obviously it’s possible to set theFix Version/s to the exact release the backportis targeting, but in general this isn’t recommended unlessyou are targeting a feature release in ramp down. When a change isintegrated to an update release repository, the bots will look atthe main issue as indicated in the PR title, and look for backportswith the currentN.0.x release version asFix Version/s, if no such backport is found theywill look forN-pool, and if that isn’t foundeither, a new backport issue will be created. This means that ifthe backport has an exactFixVersion/s set, but is delayed and misses the releaseindicated by thisFix Version/s, anew, superfluous backport issue is created with a small mess as theresult. (SeeHow to fix anincorrect backport creation in JBS.)

Setting theFix Version/s of abackport targeted to an update release toN is alwayswrong. JDKN has already been released (or itwouldn’t be an update release) and can’t get any morefixes.

Requesting approvalsfor backports

In order to be allowed to integrate a change to one of theOpenJDK update development repositories (e.g. jdk17u-dev),an approval is required. Theofficialprocess for how to request push approval for a backportdescribes in detail how to work with JBS when requesting approvals.In short, there’s a labeljdk<release>u-fix-request that should beadded to the main JBS issue. Also put a motivation as to why theissue needs to be backported as a comment in the main issue. Oncethe label and motivation has been added, wait for the maintainersof the release to approve your request. The approval will beindicated with a label,jdk<release>u-fix-yes, added to the mainissue.

If the update release is in ramp down, changes are integrated tothe release repository (e.g. jdk17u).During ramp down the bar to get changes in is significantly higherand fixes need to be approved withjdk<release>u-critical-request /jdk<release>u-critical-yes.

If your request to backport a change is denied, but you for somereason already created the backport issue in JBS (why?!), thebackport issue should be closed asWon’t Fix.

Using theSkara tooling to help with backports

The Skara tooling includes support for backports.The officialSkara documentation describes in detail how to work with thetooling to create backport PRs onGitHub or using the CLI tools. Asdescribed in the documentation, the/backport command can be used on a commit or a PRto create the backport PR:

/backport jdk21u-dev/backport jdk jdk23/backport :jdk23

In the first example we backport the change to the JDK 21 updaterelease. To backport to other update releases, replacejdk21u with the corresponding name for the targetupdate repository.

The second and third example above will backport the change to astabilization branch, in this case JDK 23. As beforejdk is the name of the target repository, andjdk23 is the name of the stabilization branch.

Using the/backport command is the recommended wayto perform backports as the tooling will automatically handle allthe necessary steps in the background. If a backport PR is manuallycreated, set the PR title toBackport <original commithash>. This ensures that the bots will recognize it as abackport as opposed to a main fix specifically targeting an olderrelease. One can tell whether or not the bots recognized a PR as abackport by thebackport label beingadded if it’s recognized.

How tofix an incorrect backport creation in JBS

If an issue is targeted to a release and a fix referring to thatissue is integrated to a different release repository, then abackport issue is automatically created in JBS. Usually this is a“good thing”, e.g., when you are backporting a fix toan earlier release, but not always… If the main issue istargeted to a later release (due to schedule planning) but someonefinds the time to fix that issue in the current release, or if themain issue is targeted to a feature release in ramp down and thefix is integrated to the master branch, then the issue should beretargeted to the correct release before integrating the fix.However, sometimes we forget.

Here’s how to fix that:

1. Reopen thebackport issue that was createdautomatically

   • Use a comment like the following (in the reopen dialog):

   This change was integrated while the main issue was targeted to 'N'. The main issue has been reset to fixed in 'N+1', this backport issue has been reset to fix in 'na' and closed as Not An Issue to avoid confusion.

   • Change theFix Version/s from‘N+1’ to ‘na’.
   • Close thebackport issue asNot an Issue. Note:Closed,notResolved

   Even if you intend to backport the issue from ‘N+1’to ‘N’ you shouldn’t reuse this backport issue.The existing (bad) push notification comment and the later to beadded correct push notification comment will look very similar andit’s just a disaster waiting to happen to deliberately addthese to the same issue.

2. Clean up themain issue

   • Copy the push notification comment from thebackportissue to themain issue, e.g.:

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

   • Add a comment like the following to themainissue:

   This change was integrated to 'N+1' while this main issue was targeted to 'N'. This issue has been reset to fixed in 'N+1' and the Robo Duke entry was copied here.

   • Reset themain issueFixVersion/s from ‘N’ to ‘N+1’.
   • Resolve themain issue asFixed in build “team” or in build“master” depending on where the fix was integrated - orto an actual build number if the change has already made it to apromoted build (look in thebackport issue if you areunsure). Integrations to ‘openjdk/jdk’ are fixed inbuild “master” and integrations to other Projectrepositories are fixed in build “team”.

Release Notes

Release notes for a product such as the JDK are part of therelease deliverables providing a way to highlight information abouta fix, such as when it may have changed behavior, or whenit’s decided not to fix something. While what should go intoa release note isn’t something that can be precisely defined,it should describe changes that are important for a user to takeinto account when they are upgrading to the specific version. Whilerelease 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 beenfixed (or in some cases not been fixed) in a release and aregenerated with each build of a release. Any note should beconsidered as an integral part of the fix process, rather thanwaiting until the end of the release to determine what to write. InOpenJDK, release notes are currently being generated for the JDKand JDK Updates Projects.

Writing a release note

Writing the release note is the responsibility of the engineerwho owns the issue. The note should be generated before the fix isreviewed, or in the case of known issues, when it’sdetermined that a fix won’t be possible in the release theissue was found in.

When writing a release note, be prepared for rather picky reviewcomments about grammar, typos, and wording. This is for the sake ofthe Java community as a whole, as the language of the release notesets the tone for many blogs and news articles. For a widely usedproduct 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 inthe release note is correct and follows a similar style.

The release note itself is written in aJBS sub-task of the issue that is usedto integrate the change. There are a few steps to follow for therelease note to find its way from JBS to the actual release notedocument.

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

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

   • While thePriority of thesub-task is set by default to be the same as the priority of theissue itself, it can be changed to adjust in what order the releasenote is listed compared to other release notes in the same build orrelease note section.
   • Set theAssignee to the sameperson who owns the main issue.
   • TheSummary should be a onesentence synopsis that is informative (and concise) enough toattract the attention of users, developers, and maintainers whomight be impacted by the change. It should succinctly describe whathas actually changed, not be the original bug title, nor describethe problem that was being solved. It should read well as asub-section heading in a document.
   • Prefix theSummary with“Release Note:”.
   • Enter the text of the release note in theDescription field using markdown formatting,following theCommonMarkspecification. While the markdown won’t be rendered inJBS, you can usedingus to see what therelease note will look like. Note thatGithub style ascii table formatting is supported but will notdisplay correctly in the dingus page. For more information seeGeneralConventions for Release Notes below.
   • SetComponent/s andSubcomponent to the same values as the originalbug.
   • SetAffects Version/s to therelease versions for which the release note should bepublished.
   • Add therelease-note label. Thisis required for the release note to be included in the releasenotes.
   • Add the properRN-label ifapplicable to indicate what section of the release notes it shouldbe included in (seeRN-labels below).
   • Set theFix Version/s to thesame value that the main issue - in almost all cases this will bethe version of mainline.

3. Have the release note ready to be reviewed at the same time asthe code is reviewed. If it’s later determined that a releasenote is necessary, then go back to the same engineers who reviewedthe fix to review the release note. Special care should be takenwhen writing a release note that will cover changes related to avulnerability fix in order to avoid describing technical details ofhow it could have been exploited.

4. When you are done,Resolve the release note sub-task asDelivered. Only release notes where the sub-task hasbeen resolved asDelivered is considered to be part ofthe EA/GA release notes. To avoid mixing up the release notes withthe code fixes that have gone into a particular release or build,we don’t useResolved/Fixed.

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

For examples of well written release note issues in JBS, seeJDK-8276929 orJDK-8278458.

General conventionsfor release notes

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

• Release notes should be no longer than 2-3 paragraphs.

• Don’t repeat information that will be included in updatesto the docs, keep it to a high level summary or key changes.

• Note that where the changes are more fully documented in the JDKdocumentation, then refer to that document for details. Whencovering a change in behavior provide some idea to what can be doneif a developer or user encounters problems from the change.

• Don’t include graphics etc. Refer to the main docs ifthere are more details that need explaining.

• Don’t include your name or affiliation, make sure however,you are the assignee of the release note sub-task.

• If you have a < in theSummarythen use<. For <’s in theDescription surround them byback-ticks.

• Avoid using Latin and abbreviations in the release note.

  • Use “also known as” instead of“aka”
  • Use “that is” or “to be specific”instead of “i.e.”
  • Use “for example” instead of“e.g.”

• TheSummary should be in titlecase instead of sentence case.

  • Example: Decode Error with Tomcat Version 7.x

• TheDescription should bestandardized to follow this pattern:

  • Sentence stating the change that was made
  • Background info/context
  • Example: A new system property,jdk.disableLastUsageTracking, has been introduced todisable JRE last usage tracking for a running VM.

Advanced options

• JEP release notes
  • Summary - If the change is anactual JEP, use the JEP title.
  • Description - the JEP Summarytext have already been heavily reviewed and also approved by theProject lead. It should be the first sentence in the release notedescription. That would be analogous to the “change that wasmade” sentence in other release note descriptions. Theremaining text would be composed of the background info from theJEP.
  • Description - The JEP releasenote description should contain the link to the JEP.
  • Labels - Therelease-note=yes label should be placed on theJEP issue itself.
• Single release note for multiple changes
  • A link to the parent issue that the note is a sub-task of, willbe placed alongside the summary in the release notes. If noterelates to additional changes, then add them asRelates links to the note and add the labelRN-MultipleLinks - seeJDK-8284975 as anexample.
• Multiple release notes for the same change
  • If more than one release note is required for the same set offixes, then open additional sub-tasks with the sameAffects Version - seeJDK-8073861 as anexample.
• Release notes across backports
  • If an issue is backported to earlier releases the same notewill be used - just add the new release version in theAffects Version field of the release note.
  • Where a different release note is required, then create aseparate note with theAffectsVersion for the new release - seeJDK-8308194 andJDK-8322473 foran example.

RN-labels

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

RN-NewFeature

A new feature or enhancement in the release. TheSummary must be the item/API or newfunctionality. TheDescription mustcontain the name of the new feature, its intended function, and howa user can utilize it. Example:JDK-8315443

RN-IssueFixed

A significant issue which has been fixed. This would normallybe a regression or an issue which was unknowingly released in a newfeature. TheSummary must be asummary of the error that was fixed. TheDescription must contain a statement about whatwas fixed, how the fix effects the user, and any special conditionsthat a user should be aware of regarding the fix. Example:JDK-8184172

RN-KnownIssue

An issue that wasn’t possible to fix by the time therelease was GA’d. TheSummarymust be a summary of the error that the user sees. TheDescription must contain details about theerror, how it effects the user, and workarounds if any exist.Example:JDK-8191040

RN-Removed

Only for major releases. The release note covers an API,feature, tool etc. which has been removed from the JDK. TheSummary must be of the form“Removal of” Item/API. TheDescription must contain the list or name of theremoved items/API with (optional) the reason for its removal.Include any special conditions that a user should be aware ofregarding the removal. Example:JDK-8185066

RN-Deprecated

Only for major releases. The release notes cover an API,feature, tool etc. that has been marked as deprecated in therelease. TheSummary must be of theform “Deprecated” Item/API. TheDescription must contain the name of the itemthat has been deprecated, the reason for its deprecation, and(optional) any special conditions that a user should be aware ofregarding the possible future removal. Example:JDK-8296385

RN-Important

Used to indicate that the release note should be highlighted insome fashion, such as listing it at the beginning of the releasenotes.

RN-(distro)

Used to indicate that the release note is only relevant for aspecific JDK distribution. E.g.RN-Oracle

RN-MultipleLinks

Used to indicate that the release note should refer to multiplechanges - seeAdvanced optionssection.

RN-Change

Deprecated. This is the default and no label is needed toindicate this.

Querying the release notes

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

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

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

The JDK Release Process

The JDK Project has a well defined release process.JEP 3 describes this process indetail. This section intends to clarify some topics that oftencause questions.

Release cycle

The release cycle starts when development of a new releasebegins, and ends when that release is delivered to the public. Thecurrent release cadence is six months. This means that every sixmonths we start development of a new release, and every six monthsa new release is delivered. However, this doesn’t mean thateach release cycle is six months. As described below, the totaldevelopment time for a release (the release cycle) is actually ninemonths. Obviously this in turn doesn’t mean that all featuresare developed in nine months. Most features are developed for amuch longer time than that, and goes through long time developmentin other Project repositories, and through a series of preview andexperimental stages. But any feature that is to be included in aspecific release has a specific window of nine months to integratethe code into mainline and fix all the remaining bugs.

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

Integrating early in a release is preferable, but all newfeatures can’t be integrated at the same time. If many largechanges enters the repository at the same time it will be moredifficult to determine which change that caused all the new bugs.If you’re about to integrate a larger change you musttherefore communicate this on the relevantmailing lists to synchronize with otherProjects that may also be planning to integrate something soon.

Milestones and phases

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

The start of arelease

Since development is always ongoing in the master branch of themainline repository (openjdk/jdk), the start of anew release can be said to be when the former release is branchedfor stabilization. After the start of the release follows sixmonths of development to implement and integrate all the cool stuffthat will go into the next release. After these six months rampdown begins.

Ramp Down Phase 1(RDP1)

The ramp down of a release starts with a new branch beingcreated (the stabilization branch) from the master branch in themainline repository. During the ramp down of a release we focus onbug fixing and stabilization in order to get the JDK ready forrelease. In RDP1 you may continue to fix P1-P3 product bugs (andsome other issues) in the stabilization branch. For detailedinformation on what can be fixed when, seePush or defer during rampdown below. The start of RDP1 is essentially the deadline forintegrating JEPs and enhancements into a particular release.

All Tests Run (ATR)

ATR is not a milestone described in JEP 3, but it’s stilla concept that might be mentioned in discussions on this topic andis therefore good to know about. ATR (a.k.a. ATR Start) is thestart of an approximately six week long test period where all testsin the test plan for the given release is ran. ATR usually startsat the same time as RDP1.

Ramp Down Phase 2(RDP2)

In RDP2 the bar is higher to get changes into the release. Forproduct bugs, only P1:s and P2:s are supposed to be fixed here, andto do so an approval is needed. See theFix-RequestProcess for details on how to obtain one. All other productbugs should be deferred. SeePush or defer during rampdown below for more details. Also note that there is noguarantee that localization can be done for changes made inRDP2.

Release Candidate(RC)

Towards the end of the release cycle, when there are no moreopen product bugs targeted to the release, a stable build isselected to be the release candidate. This build will go throughadditional testing and if no more issues are found it will be thebuild released. If new bugs are found these are investigated andhopefully fixed, and a new build becomes the release candidate. TheRC phase has a few milestones with a deadline for finding acandidate build, and another for making sure the build is ready togo live.

General Availability(GA)

This is the end of the release cycle. The last releasecandidate build is made available to the public.

Push or defer during rampdown

JEP 3 contains theexact definitions for what can be done when. This is avisualization of those definitions that may or may not clarifythings.

Push and defer guidelines during ramp down

Deferring P1 and P2 bugs

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

Please note that the priority of a bug doesn’t change justbecause you want to get your fix in late in the release, or if youwant to be able to defer it. The priority is based on the severityof the bug and if it was deemed to be a P2 before, you better havea really good explanation to why that conveniently has changed bythe end of the release. Being hard to fix isnot areason to lower the priority of a bug.

Project Maintenance

ManyOpenJDKProjects build on top of the JDK source code for instance toproduce new language features, like ProjectsAmber andValhalla. When doingthis there are a number of common workflows that are dealt with bymost Project maintainers. For instance, updating the codebase(merging) to bring in the latest changes from the upstream JDKProject.

Merging JDKmainline into a Project repository

Merging changes from one git repository to another is basicallythe same thing as getting your own changes merged into the Projectrepository, with the slight twist that you don’t write allthe changes yourself, you just pull them from somewhere else.

In this example we’ll use a separate clone of the Projectrepository to perform the merge in. This can be done using branchesas well, but let’s keep it simple for now.

Init - done once

First set up your personal fork of the Project repository, inthis example calledmy-project. If you already are aContributor totheProject youmost likely have this set up. If not, seeCloning the JDK for details on how to dothat.

git clone git@github.com:OpenDuke/my-project.git project-mergecd project-mergegit remote add upstream git@github.com:openjdk/my-project.gitgit remote add mainline git@github.com:openjdk/jdk.git

We clone the personal fork (in this case we cloneOpenDuke’s personal fork) into a local directory, here calledproject-merge. We then set up two remotes,upstream andmainline.

Performing the merge

The clone we set up above is used each time you want to bringchanges from mainline in to yourProject. This is done byfirst pulling the changes from mainline and then pushing to yourpersonal fork. A regular PR will then be created which you canintegrate into your main Project repository. It sounds easy, and itis, but there are a few details below to keep in mind.

cd project-mergegit pull upstream mastergit pushgit switch -c Merge_mainlinegit fetch mainline

We start by updating the local fork with the latest changes fromthe main Project repository. Note that we then create a new branch“Merge_mainline” in which the merge willhappen. Finally we fetch all new changes from mainline.

Merging from what ever is latest isn’t usually a goodidea, mainline code is not “clean” for any givencommit. Merging JDK tags ensures you have a known quality, thosetagged commits are known to compile and pass tests. Therefore, nextwe check which tags have not been merged yet.

git tag -l "jdk-*" --no-merged

Or if you just want to see the latest tag you haven’tmerged,

git tag -l "jdk-*" --no-merged | tail --lines 1

Before merging, you may want to check what’s incoming, toget an idea of the size of the merge and look for any incomingchanges that you suspect may cause issues.

git log --topo-order --pretty=oneline --reverse ..$TAG

And finally we initiate the actual merge.

git merge $TAG

The commands above will likely run without a hitch up until thefinalgit merge. This is where you need to combine thechanges that were made in mainline with the changes that have beenmade in your Project repository. If there are no conflictsyou’re in luck, then the merge will be completely automatedand you will end up with a committed merge. If there are conflictshowever you’ll need to manually go through the files wherethe conflicts are and make sure you select the correct version foreach change. Usinggit status you can see what filesthat need to be merged. Depending on how much code yourProject has touched, thiscan be quite a bit of work.

For complicated merges, seeSharingthe work below.

Test before integration

Regardless of if you encountered conflicts or not, you shouldalways build and test your merge before integrating it to yourProject repository. Testing needs to be done even when there are notextual conflicts as changes like for instance a rename can resultin a compile or test error without any conflict. One could arguethatgit merge --no-commit could be used and havelogical errors fixed in the merge commit. However, a subsequent“Fix logical merge errors” commit, is in fact moreuseful, as it clearly shows the Project specific adjustments neededfor incoming changes.

It’s always okay to have further commits to clean up aftera merge. Hiding a large amount of reworking Project code to fitwith upstream changes in a single merge commit will make it hardfor further errors post integration to be identified.

The commit, push, and PR

Once you have a working version of your merged code you’reready to create the merge commit and push. Please note thatgit commit is only needed if there were conflicts. Ifthe changes were successfully merged bygit merge, youalready have a committed merge.

git commit -m "Merge"git push --set-upstream origin Merge_mainline

Now it’s time to create the PR onGitHub. Just opening the PR page in yourbrowser will most often be enough to see a message about new codethat was pushed to your personal fork. Click the button to createthe PR.

Make sure the PR title starts with “Merge”. You mayhave noticed that when you integrate a “normal” PR intoan OpenJDK repository, all commits that have been done in that PRwill be squashed into a single commit. For normal changes this is agood thing as each PR normally corresponds to a single JBS issue,but for a merge it would be highly undesirable to squash all thedifferent commits that you pull in from mainline. A PR with a titlethat starts with “Merge” won’t be squashed. Thatmeans that all the changes that you brought over will remainseparate changes.

It’s always a good idea to also include what was merged inthe title of the PR. If you for instance is pulling in JDK mainlineinto your Project repository it’s likely (because it’sin general a good idea) that you choose some stable EA tag inmainline to merge. Your PR title could then be something like“Merge jdk-21+2”.

Whether a merge requires a review or not is up to your Projectlead to decide. ManyProjects don’trequire this so the GitHub bots will allow you to integrate themerge as soon as theGHAs are done.(They actually allow you to integrate even before the GHAs aredone, but that’s in general not a good idea.)

Once the PR has been integrated, you can clean up your fork andits clone in preparation for the next merge.

git switch mastergit branch -d Merge_mainlinegit push -d origin Merge_mainline

These commands will remove the temporary branch that we createdto perform the merge. There’s a button in the GitHub GUI todelete the branch after you have integrated the PR. This can beused instead of the last of the three commands above (gitpush -d...).

Sharing the work

When conflicts take place in areas requiring specializedknowledge you may need help from otherContributors. Backingup the original conflicts will help if you find yourself “intoo deep”, and need assistance from otherContributors. You canadd and later remove these backups, along with a readme describingthe merge status, to the actual merge branch to aid communication(i.e. you may not be able to compile certain components).

Something like the following shell one-liner can be used toperform the backup.

git status | grep "both modified:" | while read B M FILE; do cp -v $FILE $DEST ; done

Below are two different methods of collaborating on a mergedescribed. Please note that extra commits are fine. The merge PRitself will describe any special actions that were taken in casefurther failures turn up after merge integration. Ultimately thesecommits will be squashed when integrating the project back intomainline.

1. Parking a mergewith conflicts in place

“Park” the conflicts, unresolved, in a personalfork, and let others do the further work (by sending you a patch,or opening your personal fork up to push from otherContributors). Do thisby keeping a list of unresolved conflicts (perhaps checking in saidlist to describe the merge state), and then marking them asresolved in git, committing, and pushing them to your personalfork. E.g.git add $UNRESOLVED_FILES; git commit; gitpush

Pros: All unresolved conflicts are stated andcan be worked on by multiple parties, all at once.

Cons: Broken branch in terms of compile andtest, may require temporary workaround patches to be passed aroundto complete work on specific unresolved components.

2. Incremental merging

An alternative to parking a merge with conflicts in place, is toincrementally merge up to the troublesome point. For example:

• Perform the initial merge:git merge $TAG
• Find yourself in trouble, identify which change is causing theissue.
• Abort:git merge --abort
• Find the troublesome change:git log --topo-order--pretty=oneline --reverse $(current_branch)..$TAG
• Merge up to the previous change, commit and integrate.
• Ask others to continue the merge from the troubled changeforward, how far forward is up you of course, either just thattroublesome change, or the rest of the merge up to the $TAG.
• Rinse and repeat: There may appear further conflicts requiringotherContributors’help.

Pros: All commits in the merge branch compileand test, you always have a working branch.

Cons: There is an unknown extra amount of mergework, multiple iterations create more work. For instance you mayfind yourself resolving the same files multiple times(e.g. back-out commits).

HotSpot Development

SeeWorking With PullRequests for generic guidance and requirements aroundintegrating changes. For the HotSpot codebase there are a fewadditional requirements:

• Your change must have been approved by two reviewers out ofwhich at least one is also aReviewer
• Your change must have passed through HotSpot tier 1 testingwith zero failures (See tier1 definition intest/hotspot/jtreg/TEST.groups.)

Logging

While developing your fix, you might want your code to outputsome diagnostic information. You might even want to leave somelogging in the code you check in, to facilitate future diagnostics.The appropriate way to print logging output from HotSpot is throughtheUnified LoggingFramework (JEP 158). It gives you a lot of nice features andenables common command-line options for all logging.

A basic log message can be output like this:

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. Tags associate log messageswith certain subsystems or features and the log level determinesthe importance and verbosity of the message. The most verboseoutput is trace, and the least is error. The full list of tags andlevels are available via-Xlog:help.

The basic log API looks as follows:

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

Sometimes single line printf-style logging isn’t enough.For example, it can be useful to group several log lines togetheror to use HotSpot’s outputstream API. UL supports both ofthese use cases usingLogMessage andLogStream, respectively.

LogMessage(gc, marking) lm;if(lm.is_info()){  lm.info("We are guaranteed to be");  lm.info(" grouped together");}

LogMessage will submit its output when it goes outof scope.

LogStream is typically used when a singleprintf-style format string becomes unwieldy.

LogStream st(Log(gc, marking)::info());if(st.is_enabled()){// Print without newline  st.print("I'm printing a lot of%s ","arguments");  st.print("With a lot of extra info%d ",3);// Print with newline (cr stands for carriage return)  st.print_cr("and so it's useful to use a stream");}

If you need to print multiple lines grouped together withcomplex formatting requirements thenNonInterleavingLogStream is probably what youwant.

LogMessage(gc) lm;NonInterleavingLogStream st{LogLevelType::Info, lm};if(st.is_enabled()){  st.print_cr("Line one:%d%d%d ",1,2,3);  st.print("Line two:%d%d%d",4,5,6);  st.print_cr(" still line two:%d%d%d",7,8,9);}

Enabling logging

You enable logging in the JVM by using the-Xlogcommand line option specified. For example, the messages from theexamples would be visible if the JVM were run with any of thefollowing options:

-Xlog:gc+marking=info-Xlog:gc+marking-Xlog:gc*

You can have multiple-Xlog options, these areapplied in an additive manner. Consider this example:

-Xlog:gc+marking=info:stdout -Xlog:alloc=warning:stderr -Xlog:breakpoint=error:breakpoint.txt:level

This specifies that:

1. Log messages with info level and up, with tags gc and marking,to stdout.
2. Log messages with warning level and up, with tag alloc, tostderr.
3. Log messages with error level and up, with tag breakpoint, tofile breakpoint.txt, with the decorator level.

UL automatically applies a default argument of-Xlog:all=warning:stdout:uptime,level,tags whenlogging is enabled. This can be disabled by prepending-Xlog:disable to your arguments.

-Xlog:disable -Xlog:gc+marking=info -Xlog:alloc=warning

Starting the JVM with the option-Xlog:help outputsmore information and more examples.

A full description of the syntax of-Xlog isavailable inJEP158.

Code Owners

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

Area mailing lists

• Generic JDK Development:jdk-dev
• Build:build-dev
• Client Libs:client-libs-dev
• Core Libs:core-libs-dev
  • Net:net-dev
  • NIO:nio-dev
  • I18n:i18n-dev
• HotSpot:hotspot-dev
  • Compiler:hotspot-compiler-dev
  • GC:hotspot-gc-dev
  • Runtime:hotspot-runtime-dev
  • JFR:hotspot-jfr-dev
  • Serviceability:serviceability-dev
• Java Language (javac):compiler-dev
• Security:security-dev
• Tools
  • Javadoc:javadoc-dev
  • JShell:kulla-dev
  • Nashorn:nashorn-dev

Directory to area mapping

• .jcheck -Build
• bin -Build
• demo -Client Libs
• doc
• hotspot
  • cpu- Compiler, Runtime
  • os- Runtime
  • os_cpu- Compiler
  • share
    • adlc - Compiler
    • asm- Runtime
    • c1- Compiler
    • cds- Runtime
    • ci- Compiler
    • classfile - Runtime
    • code - Compiler
    • compiler - Compiler
    • gc- GC
    • include - HotSpot
    • interpreter - Runtime
    • jfr- JFR
    • jvmci - Compiler
    • libadt - Compiler
    • logging - Runtime
    • memory - GC, Runtime
    • metaprogramming - HotSpot
    • nmt- Runtime
    • oops - GC, Runtime
    • opto - Compiler
    • precompiled - HotSpot
    • prims - Runtime, Serviceability
    • runtime - Runtime
    • sanitizers - Runtime
    • services - Runtime
    • utilities - GC, Runtime
• java.base
  • Core Libs should almost always be included but Java Language,HotSpot, Security and/or I18n may also be involved.
  • [aix,linux,macosx,share,unix,windows]/classes
    • com/sun/crypto - Security
    • com/sun/security - Security
    • crypto - Security
    • [aix,linux,macosx,share,unix,windows]/internal
      • access - Core Libs, Security
      • classfile - Core Libs
      • constant - Core Libs
      • event - JFR
      • foreign - Core Libs
      • icu - Core Libs
      • invoke - Core Libs
      • io - Core Libs
      • javac - Java Language (javac)
      • jimage - Core Libs
      • jmod - Core Libs
      • jrtfs - Core Libs
      • [aix,macosx,share,unix,windows]/loader - Core Libs
      • logger - Core Libs
      • math - Core Libs
      • [share,unix,windows]/misc - Core Libs, HotSpot
      • module - Core Libs
      • org/objectweb - Core Libs
      • org/xml - Core Libs
      • perf - Runtime
      • [linux,share,unix,windows]/platform - HotSpot
      • random - Core Libs
      • ref - Core Libs, GC
      • reflect - Core Libs
      • util/random - Core Libs
      • util/regex - Core Libs
      • util/xml - Core Libs
      • vm - HotSpot
    • invoke - Core Libs
    • [share,sun,unix]/io - Core Libs
    • [macosx,share,unix,windows]/java
      • [share,unix,windows]/lang - Core Libs
      • math - Core Libs
      • time - Core Libs
    • launcher - Tools, Core Libs
    • META-INF/services - Core Libs
    • [javax,macosx]/net - Net
    • [aix,java,linux,macosx,unix,windows]/nio - NIO
    • reflect - Core Libs
    • [apple,java,javax,macosx,unix,windows]/security - Security
    • [java,sun]/text - I18n
    • [java,macosx,windows]/util - I18n, Core Libs
  • [aix,share,unix,windows]/conf
    • sdp - Net
    • security - Security
  • [share,windows]/legal
  • man
    • java.md - Tools, HotSpot
    • keytool.md - Security
  • [aix,linux,macosx,share,unix,windows]/native
    • common
    • [share,unix,windows]/include - Runtime, Core Libs
    • jspawnhelper - Tools
    • [share,unix,windows]/launcher - Tools
    • libfallbackLinker - Core Libs
    • [aix,linux,macosx,share,unix,windows]/libjava - Core Libs
    • [share,unix,windows]/libjimage - Core Libs
    • [aix,macosx,share,unix,windows]/libjli - Tools, Core Libs
    • libjsig - HotSpot
    • [macosx,share,unix,windows]/libnet - Net
    • [aix,linux,macosx,share,unix,windows]/libnio - NIO
    • libosxsecurity - Security
    • libsimdsort - Core Libs
    • [aix,share,windows]/libsyslookup - Core Libs
    • libverify - Runtime
    • libzip - Core Libs
  • share/data
    • blockedcertsconverter - Security
    • cacerts - Security
    • currency - I18n
    • lsrdata - I18n
    • publicsuffixlist - Client Libs
    • tzdata - I18n
    • unicodedata - I18n
• java.compiler- Java Language (javac)
• java.datatransfer- Client Libs
• java.desktop- Client Libs
• java.instrument- Serviceability
• java.logging- Core Libs
• java.management- Serviceability
• java.management.rmi - Serviceability
• java.naming- Core Libs
• java.net.http- Net
• java.prefs- Core Libs
• java.rmi- Core Libs
• java.scripting- Tools
• java.se- Core Libs
• java.security.jgss - Security
• java.security.sasl - Security
• java.smartcardio- Security
• java.sql- Core Libs
• java.sql.rowset- Core Libs
• java.transaction.xa - Core Libs
• java.xml- Core Libs
• java.xml.crypto- Security
• jdk.accessibility- Client Libs
• jdk.attach- Serviceability
• jdk.charsets- I18n, Core Libs
• jdk.compiler- Java Language (javac)
• jdk.crypto.cryptoki - Security
• jdk.crypto.ec- Security
• jdk.crypto.mscapi- Security
• jdk.dynalink- Tools
• jdk.editpad- JShell
• jdk.graal.compiler - Compiler
• jdk.graal.compiler.management - Compiler
• jdk.hotspot.agent- Serviceability
• jdk.httpserver- Net
• jdk.incubator.vector - Compiler
• jdk.internal.ed- JShell
• jdk.internal.jvmstat - Serviceability
• jdk.internal.le- JShell
• jdk.internal.md- Tools
• jdk.internal.opt- Tools
• jdk.internal.vm.ci - Compiler
• jdk.jartool- Tools
• jdk.javadoc- Javadoc
• jdk.jcmd- Serviceability
• jdk.jconsole- Serviceability
• jdk.jdeps- Core Libs
• jdk.jdi- Serviceability
• jdk.jdwp.agent- Serviceability
• jdk.jfr- JFR
• jdk.jlink- Tools
• jdk.jpackage- Core Libs
• jdk.jshell- JShell
• jdk.jsobject- Tools
• jdk.jstatd- Serviceability
• jdk.localedata- I18n
• jdk.management- Serviceability
• jdk.management.agent - Serviceability
• jdk.management.jfr - Runtime
• jdk.naming.dns- Core Libs
• jdk.naming.rmi- Core Libs
• jdk.net- Net
• jdk.nio.mapmode- NIO
• jdk.sctp- Net
• jdk.security.auth- Security
• jdk.security.jgss- Security
• jdk.unsupported- Core Libs
• jdk.unsupported.desktop - Client Libs
• jdk.xml.dom- Core Libs
• jdk.zipfs- Core Libs
• make -Build
• test
  • The test directories follow to a large part the same structureas the source code insrc. The owners are the same fordirectories with the same names.
• utils

Directories removed

• hotspot
  • *.jdk – Compiler (Removed in10)
  • share
    • aot – Compiler (Removed in17)
    • shark – Compiler (Removed in10)
    • trace – Runtime (Removed in11)
• java.base
  • share/lib – Security (Removed in24)
  • windows/lib – Security (Removed in24)
• jdk.aot – Compiler (Removed in17)
• jdk.crypto.ucrypto – Security (Removed in12)
  • only available on Solaris
• jdk.incubator.concurrent – Core Libs(Removed in21)
• jdk.internal.vm.compiler – Compiler (Removedin22)
• jdk.internal.vm.compiler.management –Compiler (Removed in22)
• jdk.pack – Tools (Removed in14)
• jdk.random – Core Libs (Removed in23)
• jdk.rmic – Core Libs (Removed in15)
• jdk.scripting.nashorn – Tools (Removed in15)
• jdk.scripting.nashorn.shell – Tools (Removedin15)

About This Guide

This guide is being maintained through theOpenJDK Developers’ GuideProject. The source repository is available atGitHub. The revision hash atthe bottom of this page refers to the last published commit.

Comments and questions may be sent toguide-dev@openjdk.org. Pleaselet us know if there’s anything in the guide that isn’tclear.