Draft proposal: JEP 2.0

[mark.reinhold at oracle.com]

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?

(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.)

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

> 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?

> 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?

Thanks for your comments!

- Mark