Draft proposal: JEP 2.0

[John Coomes]

mark.reinhold at oracle.com wrote:
> 2014/4/9 2:41 -0700, bob.vandette at oracle.com:
> > I like the idea of using JIRA for the JEP process but ...
> > 
> > Why are you proposing to continue supporting some of the JEP content
> > in Mercurial form rather than using the description field in JBS and
> > providing a template for this area of the JIRA entry?  We've done this
> > successfully for internal project tracking.
> 
> The short answer: JEPs are structured, long-form documents, and JIRA is
> not an effective tool for creating, editing, curating, and presenting a
> collection of such documents.
> 
> The longer answer:
> 
>   - Some people, including yours truly, find any amount of non-trivial
>     text editing in a web browser to be extraordinarily painful.  Maybe
>     it's just me, but if I can't edit something in Emacs then it just
>     isn't real.  (Yes, you can cut and paste individual text areas back
>     and forth, but that's too tedious to bear.)
> 
>   - Incoming JEPs invariably require at least some light copy-editing.
>     Some JEPs require much more than that.  I'm not going to do all that
>     work in a web browser, nor am I going to ask anyone else to do so.

I'm a long-time emacs user--even this email was written in emacs--yet
despite my strong preference, I think the disadvantages of splitting
JEPs across two management systems outweigh benefits like easier
editing or clear diffs.

If JEPS are split, we immediately run into consistency problems.  In a
follow-up on this thread, you mentioned eliminating almost all
duplicate headers, except the issue, title and a few others, and
implementing consistency checks.  But every field that is duplicated
would need a rule about how and where it can be changed.  What if I
want to change the Title?  Do I do that in JBS, mercurial, or both?
What if I change the issue in the mercurial document?  How can the
system automatically verify that the new issue is correct (or not)?

I'd really rather not have to define and explain all the special
cases; each one is another burden on JEP authors and maintainers,
especially newcomers.  As is the need to know two methods to update
the different parts of a JEP.  Also, I think any effort spent
automating the consistency checks would be better spent customizing
JIRA.

>   - The largest constituency for JEPs is the people who read them, not
>     those who write or edit them.  JIRA, unfortunately, does not do a
>     very good job of displaying large bodies of structured text.  It's
>     certainly possible to encode a long-form text document into some
>     text fields in a JIRA issue, but the result is far from easy to
>     read, never mind actually attractive.

If the JIRA display does end up being that ungainly, then a read-only
view (accessed via REST) could be made that extracts the necessary
data from the JIRA db and formats it nicely.  I wouldn't find that
necessary, certainly not initially.

It might be worth exploring, though, since we could then better
separate content from formatting.

>   - JIRA's history display is fairly primitive, showing just the new
>     and old values for each field modified in a particular transaction.
>     To comprehend the changes to a long document over time you really
>     need something more like an actual diff.

If JEPs are split, it will be extremely tedious to get a history of
the entire JEP (both issue and document), or to correlate events
across the two systems.  I'd have to cut and paste JIRA history and
mercurial history (into emacs :-)) and manually compare.  I'd much
prefer a single system for anything like that, and would be willing to
cut-n-paste to/from emacs to avoid it.

If truly needed, we should customize Jira to display better diffs for
JEP fields.  But I can certainly live with what's there.

> Now perhaps we can eventually customize JIRA and the systems around it
> to overcome these issues, but unless and until we do so I think we'll
> all be better served by continuing to create and maintain the bodies of
> JEPs as Markdown documents in Mercurial while tracking their workflow
> status and related tasks in JBS.

If we split JEPS, then once we do get JIRA customized, it will require
"JEP 3.0" (a significant process change) to move everything into JIRA.
I'd much rather have JEP 2.0 move everything into JIRA now so we get a
consistent, if not necessarily pretty, view of JEPs.  Then the
beautification & ease of use can be done over time, without changing
the process.

-John