Draft proposal: JEP 2.0

[mark.reinhold at oracle.com]

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.

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

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

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.

- Mark