Welcome to the Compatibility & Specification Review (CSR) Group!

The Compatibility & Specification Review (CSR) Group is empowered to review interface changes proposed within active JDK Release Projects. CSR group discussions are conducted on its mailing list.

A dashboard of active CSR requests is maintained in JBS, the JDK bug system.

CSR Background and Overview

The Java platform enjoys both breadth of use and longevity; over two and a half decades after its introduction, it remains one of the most popular programming platforms. A core tenet of the Java platform has been the importance of high-quality specifications, specifications favoring precision, explicitness, and completeness. The Java language, virtual machine, and API specifications are foundational documents for the Java ecosystem. The precision of these specifications, combined with a strong commitment to cross-release compatibility, allows applications and libraries to generally "just work" across releases.

A key component to ensuring and maintaining the quality of the specifications was the "CCC" process, originated at Sun Microsystems, which was dedicated to looking after compatibility and specification concerns, aiming to balance stability with progress to help keep Java vibrant. The role played by the CCC process has now been transferred to the Compatibility & Specification Review (CSR) OpenJDK Group, providing transparency and ensuring wider community input.

The primary role of the CSR Group is to review all changes to the JDK's exported interfaces. The term "interfaces" in this case meaning not only Java programming language interface types, but more generally the protocols between the JDK and users of the JDK. This review typically focuses on specification changes. However, implementation-only changes may also merit review if they have sufficiently large or broad behavioral compatibility impact. Secondarily, the CSR is also a resource to provide feedback to engineers working on Java platform APIs. The CSR process fulfills an archival function as well, keeping stand-alone records of API and interface changes.

CSR Workflows

In the simplest one-phase workflow, a CSR request is first drafted by the assignee (and other engineers working on the request). After being reviewed by at least one engineer familiar with that technology area, the request is Finalized by the assignee. After being Finalized, the CSR reviews the request and if there are no problems or shortcomings with the request it will be Approved by the CSR lead.

In the two-phase workflow, after the initial CSR proposal is drafted, it is moved by the assignee to the Proposed state to gather an initial round of feedback. Once the proposal is mature enough to advance, the CSR lead moves it to the intermediate Provisional state. Possibly after additional refinement and additional reviewers, the proposal is Finalized by the assignee to request the second phase of CSR review.

If problems are identified during CSR review that are serious enough to prevent the request from advancing toward approval, the CSR request can be moved to the Pended state by CSR reviewers. After the concerns are addressed by the assignee, the request can then resume either the two-phase or one-phase process.

General JDK Compatibility Policy

The general compatibility policy for exported APIs implemented in the JDK is:

Don't break binary compatibility (as defined in the Java Language Specification) without sufficient cause.
Avoid introducing source incompatibilities.
Manage behavioral compatibility changes.

One sufficient cause for breaking binary compatibility is removing a an API deprecated for removal in an earlier release, as described in the enhanced deprecation policy. The different kinds of compatibility can be subtle and are discussed in detail elsewhere. Analogous versions of the policy apply to non-API parts of the platform.

Kinds of Compatibility

FAQs

Resources