What kinds of changes need a JEP? (original) (raw)

mark.reinhold at oracle.com mark.reinhold at oracle.com
Mon Nov 6 09:14:41 UTC 2017

I'm working on an overall update of the JEP process documents, which have been in a draft state for too long now.

One issue we can discuss independently is that of the criteria for what kinds of changes need a JEP. The primary process document, JEP 1, currently states [1]:

An enhancement is an effort to design and implement a nontrivial change to the JDK code base or to do some other kind of work whose goals, progress, and result are worth communicating broadly. A JDK Enhancement Proposal (hereinafter "JEP") should be drafted for any work that meets at least one of the following criteria:

- It requires two or more weeks of engineering effort, - It makes a significant change to the JDK, or to the processes and infrastructure by which it is developed, or - It is in high demand by developers or customers.

Based on the experience of using the JEP process in one form or another for both JDK 8 and JDK 9, and looking ahead to the six-month release cadence, there are at least three ways in which these criteria could be improved.

(1) Do not mandate a JEP for a change just because that change requires two or more weeks of engineering effort.

Several committers and reviewers have observed that the first of the above criteria, "requires two or more weeks of engineering effort," is at odds with the preceding definition of "enhancement," namely a change that's "worth communicating broadly," especially when that means running it through the JEP process for candidate review, target proposal, and so forth.

Some changes can take more than two weeks of effort but aren't worth the effort to communicate broadly via the JEP process, particularly if they mainly concern developers of the JDK itself and have minimal impact on those who use and deploy the JDK. Examples include, but are not limited to, straightforward performance enhancements, refactorings of internal implementation code, improvements to tests, and merges of upstream code that have little or no effect on exported APIs. Such changes can be communicated adequately via ordinary enhancement issues in JBS, in CSR issues when exported APIs or other public interfaces are affected, and in the public reviews of such changes that we already do.

We could reduce the overhead of these sorts of changes by dropping the first criterion, so that we no longer mandate a JEP for a change that merely "requires two or more weeks of engineering effort," and adding a criterion to require a JEP for a change that can't be communicated adequately via normal JBS enhancement or CSR issues.

(2) Do not use the JEP process to track changes in development processes or infrastructure.

In practice we just haven't used the JEP process for these purposes. The processes by which we stabilized JDK 8 and JDK 9, e.g., were proposed and discussed on development mailing lists and documented on project-specific web pages. The same is true of the CSR process. We seem to have gotten along fine without using the JEP process as a meta-process for all other processes, so let's drop this part of the second criterion.

Insofar as we've had "infrastructure" JEPs, they've been for enhancements to the infrastructure of the JDK's build system rather than to software or systems outside of the JDK, which was the original intent. Such JEPs could as easily be characterized as "feature" JEPs, so we can drop the "infrastructure" part of the second criterion also.

(3) Do mandate JEPs for risky changes.

A strict, six-month release cadence leaves few opportunities to repair or back out bad changes. A change that carries significant risk is worth communicating broadly, and can benefit from the additional scrutiny that it will receive when it's proposed to target a specific release.

                              * * *

Here's a proposed new list of criteria that incorporates these changes.

A JEP should be drafted for a body of work when at least one of the following is true:

Comments?

[1] http://openjdk.java.net/jeps/1#Overview

More information about the jdk-dev mailing list