Draft proposal: JEP 2.0

[Stefan Karlsson]

On 2014-04-16 10:16, Staffan Larsen wrote:
> On 16 apr 2014, at 09:14, Bengt Rutisson <bengt.rutisson at oracle.com> wrote:
>
>> 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.
> If we can’t enable markup mode in the JIRA field, then maybe the openjdk wiki is a better place than markdown files in a mercurial repository?

Is there a reason why we can't/won't enable markup mode in the JIRA field?

StefanK

>
> I assume that the goal is for the text of the JEPs to be living updated document that would change as a JEP is taken from the initial idea into a deliverable feature. If that is the case, then it is absolutely necessary that the text be easy to update by the author or it will be just another dead document.
>
> /Staffan
>
>
>> 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.
>>
>> Bengt
>>> 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.