Draft proposal: JEP 2.0

[Jonathan Gibbons]

On 04/16/2014 01:20 AM, Stefan Karlsson wrote:
>
> 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?

I know we didn't enable markup mode on the fields that were used to 
store the info that was imported from the legacy bug system, but here 
we're talking about new fields.   And, from the Atlassian documentation, 
it seems we should be able to configure the mode on a per-field basis...

https://confluence.atlassian.com/display/JIRA/Configuring+Renderers
> Renderers are configured on a per field basis. To configure a renderer 
> for a particular field, see Specifying Field Behavior 
> <https://confluence.atlassian.com/display/JIRA/Specifying+Field+Behavior>. 
> Note that you can configure the same field differently for different 
> projects and issue types — see Associating Field Behavior with Issue 
> Types 
> <https://confluence.atlassian.com/display/JIRA/Associating+Field+Behavior+with+Issue+Types>.

-- Jon



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