Change Planning and Guidelines
This section describes the development process of identifying a bug or enhancement (formerly "Request for Enhancement" (RFE)) and providing a solution. The instructions assume that the Contributor already has a working build environment and has some familiarity with an existing OpenJDK Project and its repositories.
Three classes of changes are treated in separate sections:
- Fixing a Bug provides a step-by-step workflow for fixing a simple bug. Of particular note is the list of noreg bug labels for changes which do not have regression tests.
- Adding an API is TBD.
- Adding a Feature/JSR is TBD.
This is the list of steps which should be performed when fixing a small bug. Small bugs include typos in code or specification, algorithm improvements for correctness or performance, and code changes required to correctly implement the specification.
Some steps refer to operations which can not be performed directly without the assistance of a Oracle engineer. For example, any changes to the bug database fall into this category. Since these steps are required, external contributors are urged to work with their Sponsors to complete these tasks. Of course, the goal is to eventually make it possible for all Contributors to follow these guidelines with full access to the required tools.
For the purposes of brevity this document will use the term "bug" to refer to both bugs and enhancements unless otherwise noted. Hence "fix for a bug" could also imply "implementation for an enhancement".
- 1. Discuss the intended change
- Send an e-mail to the appropriate development alias for the
Project that maintains the
code. The e-mail should have a subject line of the form:
6543210: My favorite bug
6543210is replaced with the actual bug id number or "[NEW BUG]" if the bug id is not known and
My favorite bugis replaced with the bug's summary. The message should describe the intended change, which components may be affected, and any other risks or concerns.
- 2. Does a bug id exist for the work?
Y Continue N Create a bug in an appropriate component/sub-component. If the bug should not be publically visible, set the "Security Level" to "confidential".
- 3. Set the bug status to "Open"
- This communicates intent to fix the bug to other members of the Project. It also sets the expectation for downstream teams such as SQE and JCK that the bug will be fixed in an upcoming integration.
- 4. Does the fix for the bug require a specification change, directly affect an external interface, or otherwise have a compatibility impact?
Y Submission of a CCC request is required. Work may begin after the request has been accepted by the CCC; the changeset implementing the fix may be committed to a project forest after the request has been approved by the CCC. A description of the CCC requirements may be found in Review Bodies. N Continue
- 5. Fix the bug
- Assuming that the development team approves of the intended approach, begin working on the code using the latest source available from the appropriate OpenJDK Project repository.
- 6. Is it possible to write a test to detect the bug?
Y For bugs, provide a jtreg regression test as part of the changeset. For enhancements an that directly affect one or more exported interfaces, add an adequate set of jtreg unit tests as part of the changeset.
An entirely new test (or tests) may not be required. For example, if the bug is an existing regression test failure, then when fixing the bug you should just add the new bug ID to the @bug tag of the failing regression test, even if the test did not need to be updated.
N An explanation for why a test is unnecessary or infeasible is required. Such an explanation is recorded by adding a label, and possibly a comment, to the bug report. The label has the prefix for regression tests and "nounit" for unit tests. The suffixes and their meanings are as follows:
- Change can be verified by running an existing SQE test suite; the bug should identify the suite and the specific test case(s).
- Change can be verified by running the JCK; the bug should identify the specific test case(s).
- Change can be verified by running an existing external test suite; the bug should identify the suite and the specific test case(s).
- Change only affects documentation.
- Change only affects demo code.
- Change only affects build infrastructure (makefiles, copyrights, scripts, etc.).
- Change is a fix to a regression or unit test itself.
- Change is for a performance bug for which writing a regression test is infeasible; the bug should describe how to verify the fix.
- It is too hard to write a regression or unit test for this bug (e.g., theoretical race condition, complex setup, reboot required, editing of installed files required, specific graphics card required); the bug should explain why.
- Testing requires a very long running time (e.g., more than a few minutes).
- Testing requires an unreasonable quantity of resources (e.g., tens of gigabytes of filesystem space).
- Change is so trivial that nothing could possibly go wrong with it.
- Change is a cleanup or refactoring of existing code that is covered by existing tests.
- Change only affects localized text.
- Change is a reversion of a previous faulty change.
- Regression or unit test is unnecessary or infeasible for some other reason; the bug report should explain why.
Examples: If a bug fix only corrects a change in the build system, then add the "noreg-build" label to the corresponding bug. If change improves loop optimizations in HotSpot, then add "nounit-perf" to the corresponding bug.
- 7. Is modification of shared Java code needed?
Y It is often sufficient to build and test on a single platform, but sometimes it is not. Use discretion. N Continue
- 8. Is modification of shared C code needed?
Y Build and test on at least one instance of all three of the supported operating systems (Solaris, Linux, and Windows). N Continue
- 9. Is modification of C or Java platform-specific code needed?
Y Build and test on all relevant platforms. Code under
src/solarisbuilds on both Solaris and Linux, despite its name.
- 10. Run relevant regression and unit tests on all relevant platforms
- These include tests for external interfaces as well as other kinds of tests, e.g., HotSpot tests that use internal verification mechanisms. See Testing Changes for more details.
- 11. Run relevant JCK tests on all relevant platforms
- Running JCK tests is particularly important if the change may have unexpected side-effects. See JCK Acquisition for more details.
- 12. Request a review of the changes by sending an e-mail to the development alias
- A patch can be submitted as described in Contributing. Alternatively, a "webrev" may be
generated and uploaded to the community code review server. The
complete webrev generation and upload procedure is described at
Changeset pushes before the Feature Complete require at least one Reviewer; pushes after the Feature Complete require at least two Reviewers. In either case, the more the merrier. Some teams may require more Reviewers. Check with members of the Project.
Reviewers should examine not only the code being added or changed but also the relevant unit or regression tests.
A change may require multiple Reviewers because it affects multiple areas. Reviewers should be aware that they take full responsibility for the appropriateness and correctness of any changes in their area of expertise. If something goes wrong (e.g., the build breaks) and the change's author is unavailable, they may be asked to deal with the problem. Potential Reviewers are encouraged to refuse to review code for which they are not qualified.
- 13. Create a changeset
- Follow the instructions in Producing a Changeset.
- 14. Update the bug content
- Bug descriptions and comments are visible to the public and should be written in a professional manner. Comments not appropriate for public consumption should be marked as "Confidential" in when they're added to the bug. (The default is "Viewable by All Users".)
- 15. Push the changeset into the Project's forest
- Follow the instructions in Producing a Changeset. If working
with a Sponsor, send the changeset to the development mailing list
so that they can handle the final push.
The push will trigger a update to the bug which will make the following changes:
- Set the bug's "Status" to "Resolved" and "Resolution to "Fixed".
- Set the bug's "Fix Version/s" to an appropriate release.
- Set the bug's "Resolved in Build" to "team".
- Add a Comment containing a reference to the changeset.
Congratulations! Your changeset will now make its way towards a promoted build. When the changeset becomes part of a promoted build, the bug's "Resolved in Build" will have a value of "b[1-9][0-9]*" to indicate the build number.
This section will cover additional considerations for changes that add new public APIs. For instance, they need to be implementable on all platforms.
This section will describe the process for adding new functionality which requires more than just a few new APIs. In particular, this will cover how the JSR process interacts with the OpenJDK development life cycle.