What kinds of changes need a JEP?

[Brian Goetz]

At the risk of being redundant, I’ll add that a JEP should be required for:
 - Any language feature;
 - Any change to the class file format.

While one could argue that these are subsumed by the other criteria, it is best to be explicit.  

> On Nov 6, 2017, at 10:14 AM, mark.reinhold at oracle.com wrote:
> 
> 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