Change Planning and Guidelines

version 0.01
« Previous • TOC • Next »

This section describes the development process of identifying a bug or 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 source tree.

Three classes of changes are treated in separate sections:

Fixing a Bug

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

Some steps refer to operations which can not be performed directly without the assistance of a Sun 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 RFEs unless otherwise noted. Hence "fix for a bug" could also imply "implementation for an RFE".

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
where 6543210 is replaced with the actual bug id number or "[NEW BUG]" if the bug id is not known and My favorite bug is replaced with the bug's synopsis. 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 category/sub-category. If the bug should not be publically visible, add the "confidential" keyword. Bugs that contain the word "security" in any section also automatically excluded from the SDN unless the "jdcinclude" keyword is present.
3. Set the bug state to "FIP" ("Fix in Progress")
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 RFEs an that directly affect one or more exported interfaces, add an adequate set of jtreg unit tests as part of the changeset.
N An explanation for why a test is unnecessary or infeasible is required. Such an explanation is recorded by adding a keyword, and possibly some text, to the bug report. The keyword has the prefix "noreg" for regression tests and "nounit" for unit tests. The suffixes and their meanings are as follows:
-sqe
Change can be verified by running an existing SQE test suite; the bug should identify the suite and the specific test case(s).
-jck
Change can be verified by running the JCK; the bug should identify the specific test case(s).
-external
Change can be verified by running an existing external test suite; the bug should identify the suite and the specific test case(s). XXX Is this still appropriate? It's not obvious what types of test suites fall into this category.
-doc
Change only affects documentation.
-demo
Change only affects demo code.
-build
Change only affects build infrastructure (makefiles, copyrights, scripts, etc.).
-self
Change is a fix to a regression or unit test itself.
-perf
Change is for a performance bug for which writing a regression test is infeasible; the bug should describe how to verify the fix.
-hard
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.
-long
Testing requires a very long running time (e.g., more than a few minutes).
-big
Testing requires an unreasonable quantity of resources (e.g., tens of gigabytes of filesystem space).
-trivial
Change is so trivial that nothing could possibly go wrong with it.
-cleanup
Change is a cleanup or refactoring of existing code that is covered by existing tests.
-l10n
Change only affects localized text.
-undo
Change is a reversion of a previous faulty change.
-other
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 a makefile, then add the "noreg-build" keyword 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/solaris builds on both Solaris and Linux, despite its name.
N Continue
10. Run relevant regression and unit tests on all relevant platforms
These include tests for external interfaces as well as other kinds of tests, e.g., HotSpot tests that use internal verification mechanisms. 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
For now, submit a patch as described in Contributing.

Changeset pushes before the development freeze require at least one reviewer; pushes after the development freeze require at least two reviewers. In either case, the more the merrier. Some groups 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, suggested fixes, and evaluations are visible to the public and should be written in a professional manner. Content not appropriate for public consumption should be placed in the comments section.

If you need to refer to a specific individual in a publicly-visible section of a bug then use an e-mail address ("joe.smith(at)sun.com") rather than a plain name ("Joe Smith"). E-mail addresses are anonymized when bugs are displayed on the SDN; plain names are not.
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.
16. Set the bug state to "FIX" ("FIXed")
Mark the bug FIXed against the appropriate release. Do not mark it INTegrated — that will be done when the project's forest is next integrated into the MASTER.

Adding an API

TBD

This section will cover additional considerations for changes that add new public APIs. For instance, they need to be implementable on all platforms.

Adding a Feature/JSR

TBD

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.

version 0.01
« Previous • TOC • Next »