JEP draft: JEP 2.0, draft 2

AuthorMark Reinhold
OrganizationOracle
Created2013/12/16
Updated2014/5/5
TypeProcess
StateDraft
Discussiondiscuss at openjdk dot java dot net

Summary

Extend the JEP Process to cover the creation and maintenance of the set of features intended for delivery in a JDK Release Project, the tracking of the development status of each feature, and the scheduling of releases themselves. Ensure that the revised process can also be used to track work that is of broad interest but not targeted to a specific release. The process may be used by other Projects as they see fit.

Goals

We use the current JEP Process to collect, review, sort, and evaluate proposals for enhancements to the JDK. The ongoing result of this process is the JDK Roadmap, a collection of feature ideas and other proposals for consideration by JDK Release Projects and related efforts. The Roadmap is intended to extend at least three years into the future so as to allow sufficient time for the most complex proposals to be investigated, defined, and implemented.

The JEP Process also records the targeting of Feature JEPs to particular releases, but it says nothing about how we make targeting decisions, how feature work is tracked as a release progresses, or how a release’s overall schedule is created and maintained.

We also use the JEP Process to document work that is not associated with a particular release, such as forward-looking research or improvements to our processes and infrastructure. The JEP Process currently does nothing to track the status of such efforts.

This proposal aims to fill these gaps. The existing goals of the JEP Process will not change, nor will its current guidance on making decisions and building consensus, even around wacky ideas. The state model and the proposal format, however, will be revised.

If this proposal is adopted then the end result will be new versions of JEP 1 and JEP 2.

Planning

At a high level, the planning part of the revised JEP Process is concerned with the set of features targeted to a release being developed in a specific OpenJDK Project, and with the schedule of the release itself. It works as follows:

NOTE: Per the Bylaws, every Reviewer of a Project is also a Committer to that Project.

Tracking

Once a Feature JEP is targeted to a release, we need a way to track progress on its development. We will leverage the JDK Bug System (JBS) for this purpose by introducing a new “JEP” issue type. JEP issues will replace the current Mercurial repository of JEP documents, and eventually all existing JEPs will be moved into JBS.

Non-Feature JEPs, of type Infrastructure, Informational, and Process, will also be tracked in this way.

Release schedules will not be tracked in JBS. Project Leads are expected to document release schedules on appropriate Project-related web or wiki pages.

Information in JEP issues

JEP issues in JBS will have the standard JIRA fields, with the following interpretations relative to JEP 1.0 terminology. Fields preceded with ‘+‘ must not be empty.

 JBS                                   JEP 1.0
 ----------------------------------    ----------------------------
+Summary: <text>                       Title
+Assignee: <Committer name>            Owner
+Reporter: <user name>                 Original author
+Created: <date>                       Created
+Updated: <date>                       Updated
+Type: JEP                             n/a
 Priority: <priority>                  NEW (see below)
 Component/s: <component>              Component
 Labels: <labels>                      NEW
+Status: <status>                      State (roughly)
 Resolution: <resolution>              NEW (when status = Closed)
 Fix Version/s: <version>              Release
 Due Date: <date>                      NEW

(Some of the JBS field names are less than ideal but they are, sadly, not easily customizable.)

JEP issues will, additionally, have some custom fields:

 JBS                                   JEP 1.0
 ----------------------------------    ----------------------------
+Author: <name>                        Author
 JEP number: [0-9]+                    JEP
+JEP Type: Feature                     Type
           | Infrastructure
           | Informational
           | Process
+Exposure: Open | Closed               Exposure
 Subcomponent: <subcomp>               Component
 Scope: SE | JDK                       Scope (must be non-empty
        | Implementation                      in Feature JEPs)
 JSR: [0-9]+( MR)?                     JSR
+Discussion: <mailing list>            Discussion
 Effort: XS | S | M | L | XL           Effort
 Duration: XS | S | M | L | XL         Duration
 Reviewed By: <Reviewer names>         Reviewed-by
 Endorsed By: <endorser names>         Endorsed-by
 Integration Due Date: <date>          NEW
 Alert Status: Green | Yellow | Red    NEW
 Alert Date: <date>                    NEW
 Alert Reason: <text>                  NEW

The JBS fields that are new relative to the JEP 1.0 template are interpreted as follows:

Further differences relative to the JEP 1.0 template:

The Component or Subcomponent fields of a JEP issue may be empty in the case of a feature that affects multiple components or subcomponents.

The Description field of a JEP issue will contain the body text of the JEP. It will be written in Markdown format, as before, and JBS will render it in appropriate HTML. The structure of the body text will not change except that the Impact section will be removed; this section has proved to be of limited value over the years, and there are better ways (e.g., a FAQ) to encourage JEP owners to analyze and document the impact of a JEP.

Workflow

The revised JEP Process has the following states and transitions for Feature and Infrastructure JEPs:

A JEP will, most often, move through the sequence of states connected by dark blue edges; light blue edges represent less-common transitions, discussed further below.

The first three states for a Feature or Infrastructure JEP are:

A JEP in the Candidate state is merely an idea worthy of consideration by JDK Release Projects and related efforts; there is no commitment that it will be delivered in any particular release.

A JEP will be assigned a JEP number, distinct from its JBS issue key, the first time it enters the Candidate state. This is for convenience of reference, and for continuity with the set of JEPs created in the JEP 1.0 process.

From this point onward a Feature JEP will, most often, move through these states:

The engineering plan documented in subtasks of a Feature JEP should include, but is not limited to, design, implementation, test development (unit, functional, performance, and conformance), and documentation. The assignee of each subtask is considered responsible for completing that subtask.

The Priority, Fix Version, Integration Due Date, and Due Date fields must not be empty in the Proposed-to-Target state or any later state. After a JEP is Targeted, only the Project Lead may modify the Priority and Fix Version fields.

A release, as a whole, is considered Feature Complete only after all of its Feature JEPs reach the Complete state.

Workflow: Uncommon paths

Sometimes a JEP will not proceed smoothly from Draft to Closed/Delivered.

If a JEP is submitted prematurely then the JEP’s owner can move it from Submitted back to Draft.

If the OpenJDK Lead determines that a Submitted JEP is not ready to enter the Candidate state, or that a Candidate JEP is no longer suitable for the JDK Roadmap, then the OpenJDK Lead will move it back to Draft.

The OpenJDK Lead can move a JEP from Submitted or Candidate to

to indicate that the JEP is not worth pursuing, or is so unlikely ever to be targeted that it’s not worth maintaining in the Roadmap.

If a JEP is moved to Proposed-to-Target prematurely then the JEP’s owner can move it back to Candidate.

If a JEP in the Draft, Submitted, Candidate, or Proposed-to-Target state is to be withdrawn because no further work on it will be done then the JEP’s owner can move it to

If the JEP is later revived then the owner can move it from Closed/Withdrawn back to Draft.

If a proposal to target a JEP to a specific release is not accepted then the Project Lead will move it back to Candidate.

If the owner of a Targeted JEP, or the relevant Project Lead, wishes to drop the JEP from the targeted release then that person can move the JEP to

in which case the Project Lead will either move the JEP back to the Candidate state, if the drop proposal is accepted, or else revert the JEP to its previous state. If the JEP is moved back to Candidate then its Fix Version, Integration Due Date, and Due Date fields will be cleared.

If a JEP is moved to Integrated prematurely then the owner can move it back to Targeted. If a JEP is moved to Complete prematurely then the owner can move it back to Integrated.

Some Infrastructure JEPs will never be targeted to a specific release, so the owner of an Infrastructure JEP can move it forward from Candidate to Closed/Delivered when work on the JEP is complete.

Workflow: Informational and Process JEPs

The states and transitions for Informational and Process JEPs are simpler:

An Active JEP is one whose information or process is currently relevant to the OpenJDK Community.

Minor revisions to an Active Informational or Process JEP may be made after appropriate discussion and review. Major revisions should be proposed and discussed in a separate JEP of the same type. The new JEP may then supersede the original, which should be moved to Closed/Withdrawn, or else the original may be updated in place, in which case the new JEP should be moved to Closed/Delivered.

Informational and Process JEPs need not adhere strictly to the standard JEP body template.

Mechanics

All existing JEPs in the Mercurial archive will be moved into JBS some time after this revised JEP Process is rolled out. Authors of JEPs submitted but not yet posted will be asked to re-draft them in JBS.

Additional changes to the JEP Process

We’ll take this opportunity to make two unrelated changes to the JEP Process: