| Author | Mark Reinhold |
| Organization | Oracle |
| Created | 2013/12/16 |
| Updated | 2014/4/8 |
| Type | Process |
| State | Draft |
| Discussion | discuss at openjdk dot java dot net |
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.
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 remain, as 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.
At a high level, the planning part of the extended 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:
Any Committer to a Project may propose to target a Feature JEP to a release of that Project after documenting a realistic delivery plan and adequate funding. The proposer should be the JEP’s owner, or arrange to become the owner.
The owner of a targeted JEP may later propose to drop that JEP from its targeted release.
The Project’s Lead may propose an initial release schedule, and thereafter propose changes to that schedule.
Proposed changes to the feature set and schedule of a release are approved by rough consensus of the Committers to the Project, as determined by the Project Lead. Any particular proposal must be open for discussion for at least one calendar week, major holidays excepted.
NOTE: Per the Bylaws, every Reviewer of a Project is also a Committer to that Project.
Once a JEP is published, 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 documents will continue to be drafted, posted, and maintained as they are today, in the form of Markdown documents in a Mercurial repository. The state information of a JEP, however, as well as additional information needed to track the actual development work on the JEP, will now reside in JBS. The owner of a JEP document will be the assignee of the corresponding JBS JEP issue.
Non-Feature JEPs, of type Research, Infrastructure, Informational, or 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.
JEP documents will continue to have the following headers, whose values are expected to change relatively infrequently (lines preceded with “+” are required):
+Title: <title>
+Author: <author's full name>
Owner: <owner's full name>
Organization: <org name>
+Created: YYYY/MM/DD
+Type: Feature | Research | Infrastructure | Informational | Process
+Exposure: Open | Closed
+Component: <component>/<sub-component>
+Scope: SE | JDK | Implementation
JSR: <number, if an active JSR>
RFE: <relevant RFE numbers>
+Discussion: <mailing-list address>
Depends: <draft names or JEP numbers>
Blocks: <draft names or JEP numbers>
Effort: XS | S | M | L | XL
Duration: XS | S | M | L | XL
+Template: 2.0
Internal-refs: <references>
Reviewed-by: <Committer names>
Endorsed-by: <Group/Area lead names>
The State, Start, Funded-by, Release, and Target headers have been dropped. To align with JBS, JEPs will adopt the JBS component/sub-component ontology.
Any RFE numbers should include the appropriate JBS project prefix (e.g., “CODETOOLS-“) unless that prefix is “JDK-“, in which case it should be omitted since it’s the default.
The format of the body of a JEP document will not change.
A JEP issue in JBS will have the following fields:
A JEP issue intentionally has no description field. Information about what is being implemented, and why, belong in the corresponding JEP document. Information about how all aspects of the JEP such as code, tests, documentation, etc., will be created and delivered, and by whom, can be placed in ancillary documents such as subtasks or linked wiki pages.
The Red/Yellow/Green alert status is interpreted as follows:
Red: Plan at serious risk, with no plan to mitigate that risk
Yellow: Plan at risk, but a credible plan is in place to mitigate that risk
Green: All is well
The JEP owner is expected to update the Alert Status on a weekly basis once a JEP is Funded and active development work is under way. If the Alert Status is Yellow or Red then the owner must use the Alert Reason field to explain what is required to return the Status to Green. This way everyone working on the release or otherwise interested in the JEP can easily understand its current state.
When a JEP document is first posted to the JEP Mercurial repository it will automagically be assigned a corresponding JEP issue in JBS. An “Issue” header will be added to the JEP document to link it to its JBS issue.
The revised JEP Process has the following states and transitions:
A JEP will, most often, first move through the following sequence of states:
Posted — Published in the JEP Mercurial repository for wider review
Submitted — By the JEP’s owner, declaring the JEP ready to be evaluated for the JDK Roadmap
Candidate — By the OpenJDK Lead, to add the JEP to the JDK Roadmap
Planning — By the JEP’s owner, to indicate that work on a plan to deliver the JEP is in progress
Funded — By the JEP’s owner, to indicate that an engineering plan for the JEP is complete and has been committed to by the individuals and organizations who will do the actual work including, but not limited to, design, implementation, functional-test development, conformance-test development, and documentation
Entering the Funded state indicates that active development on the JEP has begun.
From this point onward a Feature JEP will, most often, move through these states:
Proposed to Target — By the JEP’s owner, for a specific release
Targeted — By the Project Lead, after seeing rough consensus amongst the Committers and Reviewers of the Project
Integrated — By the JEP’s owner, after code and unit tests are integrated into the master code base
Complete — By the JEP’s owner, after related materials such as functional and system tests have been delivered and the feature has reached the point where only bug fixes are expected
Closed/Delivered — By the Project Lead, when the release ships
The Fix Version and Milestone fields of a JEP issue are initially empty, but they must have valid values for the Proposed-to-Target state and all later states.
A release, as a whole, is considered Feature Complete when all of its Feature JEPs are in the Complete state.
A JEP’s owner or the relevant Project Lead can move it from Targeted, Integrated, or Complete to
in which case the Project Lead will either move the JEP issue back to the Funded state, if the drop proposal is accepted by rough consensus, or else revert the issue to its previous state. If the issue is moved back to the Funded state then its Fix Version and Milestone information will be cleared.
A JEP’s owner can move it from Proposed-to-Target back to Funded, from Funded back to Planning, and from Planning back to Candidate.
A JEP’s owner can move it from Posted, Submitted, Candidate, Planning, Funded, or Proposed-to-Target to
to indicate that the proposal has been withdrawn and no further work on it will be done. If that condition changes at some later time then the owner can move the issue from Closed/Withdrawn back to Posted.
The owner of a non-Feature JEP can move it forward from Funded to Closed/Delivered when work on the JEP is complete. Research, Infrastructure, Informational, and Process JEPs can thus be tracked in this process even though they are never targeted to specific releases.
The OpenJDK Lead can move a JEP from Posted, Submitted, or Candidate to
to indicate that the JEP is not worth pursuing, or is so unlikely to be funded that it’s not worth maintaining in the Roadmap.
When this revised JEP Process is rolled out, in-flight JEPs will be upgraded as necessary.
We’ll implement some automated consistency checks between JEP documents and JEP issues to verify, e.g., that a JEP issue’s Summary, Assignee, and Component/Sub-Component values match those in the corresponding JEP document.
We’ll take this opportunity to make two unrelated changes to the JEP Process:
JEP Authors will be required only to be Contributors, not Committers. If a JEP’s Author is not a Committer then the Owner must be a Committer. It will remain the case that only a Committer can submit a JEP.
Create a new mailing list where large, cross-component JEPs with deep impact to the platform can be discussed until such time as they have Project-specific mailing lists.