What kinds of changes need a JEP?

[David Holmes]

On 9/11/2017 4:58 AM, Volker Simonis wrote:
> Hi Mark,
> 
> thanks for finally addressing this long standing issue! I think your
> proposal is good.
> 
> In a parallel thread [1] Brian has just describe the work on a JEP as
> follows: "For nontrivial projects, you are expected to work
> iteratively, progressively refining the design, interface,
> implementation, and test suite together, outside of the main code
> line, until it is ready, and then — and only then — do you start the
> process of proposing to target."
> 
> I think that's a pretty accurate description of a JEP and I'm inclined
> to propose to add something like the following to the conditions for a
> JEP you've defined:
> 
> 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.
> 
> and it justifies an implementation and testing outside of the main code line.
> 
> This would make it clear that a JEP is a more heavy-weight project
> than a simple enhancement and that we expect a fully working and
> tested implementation before we consider to integrate it into the
> "always feature complete" main line. It would also keep people from
> "cheating" by implementing parts of a JEP incrementally in the main
> line.

It is perfectly reasonable for JEP work to identify cleanups and 
refactorings that aid the JEP work, but which can be putback to the 
mainline as a standalone change. Without such enabling changes we would 
greatly increase the difficulty of integrating the JEP work when it is 
ready. I don't consider this "cheating".

Cheers,
David

> Regards,
> Volker
> 
> [1] http://mail.openjdk.java.net/pipermail/jdk-dev/2017-November/000138.html
> 
> 
> On Tue, Nov 7, 2017 at 5:46 PM, Brian Goetz <brian.goetz at oracle.com> wrote:
>> 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
>>