Draft proposal: JEP 2.0

[Brian Beck]

On 4/16/14 6:14 PM, Jonathan Gibbons wrote:
>
>> 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...
Enabling wiki markup for bugs & enhancements caused too much chaos with 
all the legacy data.  We tried to figure out ways to selectively turn it 
off but never succeeded.  Wiki markup is an often requested feature 
however.  Our (Infra team's) thought is to turn it on for any new issue 
type or new field that doesn't have a boat load of legacy data to 
confuse.  We've got it turned on in the JEP prototype with good results 
so far.

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