What kinds of changes need a JEP?

[Volker Simonis]

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.

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
>