What kinds of changes need a JEP?

[mark.reinhold at oracle.com]

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:

  - It makes a significant or risky change to the JDK,

  - It has a broader impact on developers and users than can reasonably
    be communicated in an ordinary enhancement or CSR issue, or

  - It is in high demand by developers or users.

Comments?

- Mark


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