Draft proposal: JEP 2.0

[Mike Duigou]

On Apr 12 2014, at 12:28 , mark.reinhold at oracle.com wrote:

> 2014/4/10 13:41 -0700, mike.duigou at oracle.com:
>> Some comments.
>> 
>> Tracking:
>> 
>> - I'll add my voice to Bob's that we want only one system of record
>> for JEPs and that should be JBS. JEPs are either managed entirely
>> within JBS or we shouldn't bother with using JBS for JEPS at all. If
>> we are going to go with the many-staged workflow described in the
>> proposal then having JBS to manage that workflow would be a huge boon.
> 
> I agree (obviously) that we should use JBS to implement the proposed new
> workflow.  As implied by my answer to Bob, though, I don't think that we
> must choose one system over the other.
> 
> What might not be clear in the current draft is that no workflow status
> is ever recorded in a JEP document.  You can draft a JEP, pass it around
> in e-mail or put it on a wiki for initial review, and then once you
> submit it for posting to the Mercurial archive it gets a JBS issue and
> the workflow is tracked in JBS.
> 
> In the current proposal some information is duplicated in both a JEP
> document and its corresponding JBS issue, hence the need for automated
> consistency checks.  To simplify things perhaps we should move as much
> information as possible from a JEP document into its JBS issue at the
> time the issue is created.  A "proto-JEP", then, would contain all the
> headers mentioned in the proposal, but once it's posted and has a JBS
> issue then the only header the document would absolutely need would be
> the "Issue" header, to link it to the issue.  (To make editing JEP
> documents easier we might want to retain a couple of other headers,
> e.g., "Title".)  The rendering of a posted JEP document would then be
> based upon information in both the Mercurial archive and JBS.
> 
> Would you prefer this kind of approach?

Very much so. I still question the value of the Mercurial 

> 
> (A related optimization would be to remove the "Impact" section from the
> document once a JEP reaches the Funded state, since by then presumably
> anyone impacted by the proposal will have been included in the JEP's
> plan.)
> 
>> - "Alert Status (updated weekly once Funded)". This seems onerous for
>> projects that are green (or irredeemably yellow). Required
>> increment-the-date weekly updates has been a significant annoyance for
>> internal processes which I would prefer not to repeat with JEPs.
> 
> I see what you mean about having to update the status weekly when a
> feature is Green.  If a feature is Yellow, though, then I don't think
> it's unreasonable to ask for a weekly update, and making such an update
> in JBS should take only a moment.  (If a feature is irredeemably Yellow
> then perhaps it shouldn't be in the Funded state, or any later state.)

The "irredeemably yellow" condition is an expression of risk and has generally occurred after funding during the development when a feature uses up all of it's schedule slack and/or meeting the originally promised timelines becomes impossible. In most cases we should not fund features with non-green levels of risk but we do sometimes end up there. In the past we have done replans to keep a feature within the existing timelines but a higher degree of risk remains. In very few cases is a replan able to reduce the risk back to "full green". Perhaps something finer grained than Green-Yellow-Red to classify schedule risk might help.

> How about "updated weekly if not Green, once Funded"?

Sounds reasonable. The greater the remaining risk, the closer the monitoring.

> 
>> Workflow:
>> 
>> - The diagram unfortunately reminds me too much of a LHC "Higgs Boson
>> detection event" graphic. Many of these states are overlapping and are
>> worked coincidentally. Since only some of them are strictly gating can
>> we collapse the softer states to a smaller number of strictly gating
>> states?
> 
> I'm all for eliminating needless states, but each one does serve a
> distinct purpose, especially in terms of communicating the status of
> work on a feature.  It's true that some kinds of work are likely to
> overlap -- just because a feature isn't yet Funded doesn't mean you
> can't, e.g., do some prototyping work (which can arguably be part of
> the Planning stage anyway).
> 
> Do you have specific suggestions of states to collapse?

I think I like Joe Darcy's suggestion of moving the terminal states (all of the closed states) to a separate categorization.

>> General:
>> 
>> - The JEP process doesn't feel very approachable to an outsider/first
>> time submitter. Either we have to provide a lot more guidance about
>> how to fill out a JEP and/or make the process simpler. ...
> 
> I agree that we could do better here.  Improving in this way would help
> submitters and it would also reduce the workload of those of us who edit
> incoming JEPs.  Perhaps we should use our wiki to collect a list of FAQ
> items and, once it settles, publish it as an informational JEP?

I think that would be very helpful and I am encouraged to see interest in this particular concern from the AdoptOpenJDK folks.

The amount of interest and enthusiasm in your proposal from the wider community is also encouraging! Moving forward!

Mike