Draft proposal: JEP 2.0

Bengt Rutisson bengt.rutisson at oracle.com
Wed Apr 16 07:14:41 UTC 2014

On 4/15/14 9:34 PM, Per Bothner wrote:
> [Sorry for the bad message linkage - I just subscribed.]
> On Apr 12 Mark Reinhold wrote:
> >  - Some people, including yours truly, find any amount of non-trivial
> >    text editing in a web browser to be extraordinarily painful.   ...
> >  - Incoming JEPs invariably require at least some light copy-editing.
> >    Some JEPs require much more than that.  ...
> As you point out "The largest constituency for JEPs is the people who
> read them, not those who write or edit them."  I think most people
> (even those of us more comfortable with Emacs) can handle editing
> in a web browser.

Totally agree.

One more comment further down.

> >    JIRA, unfortunately, does not do a
> >    very good job of displaying large bodies of structured text.
> Actually, JIRA supports rich text tolerably well - about as well
> as the Markdown use by JEP (thought it doesn't have the "escape to
> HTML" fall-back).  Of course they use their own idiosyncratic
> markup format, which matches the Confluence wiki engine.  Any text
> field can be configured to the use the "Wiki Style Renderer":
> https://confluence.atlassian.com/display/JIRA/Configuring+Renderers
> https://jira.atlassian.com/secure/WikiRendererHelpAction.jspa
> The result is quite readable, and looks decent enough.
> (There are plugins to use Markdown, but I don't believe any is 
> supported by Atlassian, so I think its more simple and robust to stick
> with the native markup format.)
> >    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.
> One could use a separate JIRA field for each JEP section, or just put
> it all in the Description field and use headings to mark the sections.
> It's not clear which is better.
> >  - 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.
> Yes, JIRA isn't very diff-friendly nor very friendly to the kind of
> workflow we're used to from Mercurial, including patches.

True, but note that the proposal is already suggesting that the "static" 
parts of a JEP should be in the Mercurial repository and that the 
"dynamic" part should be in JIRA. So, even with the current proposal we 
will be using JIRA for the tracking information that is changing the 
most. Thus, I don't think that saying that Mercurial is better at 
tracking changes is much of an argument for keeping part of the JEP there.

I think we need to decide to either have the full JEP in Mercurial or in 
JIRA. Having it in both places just does not make sense.

> I wrote some experimental tools in this area.  The idea is to use
> JIRA's REST interface, which allows you to extract the fields of an
> issue in a JSON representation - as well as optionally update them.
> I wrote a filter to convert to and from what I call "pretty JSON",
> which does line-breaking, indentation, removes the redundant commas,
> and quotes around field names.  This format is much more diff-friendly 
> - as well as friendlier to human readers and editors.  Our goal was to 
> version-control JIRA configuration information, as well as copy 
> information from one JIRA instance to another.  It seems we could
> modify these command-line tools could to make it more pleasant to diff
> (or even patch) JEP issues.

More information about the discuss mailing list