Re: [xwiki-devs] Release notes strategy for included contrib extensions

On 12 Oct 2016, at 12:34, Eduard Moraru <enygma2002(a)gmail.com> wrote: Another idea would be to use the extension page`s release notes as the

place where to write changes and then, in the XE RN, aggregate the RN of all the bundled extensions. This would cover both contrib and core extensions and would also make the extension page much nicer, since right now you can only see the documentation but have no clear picture of the changes that the application has gone through. What we are doing now does not make a lot of sense (having the page + doc in one place, and the changes of particular extensions in the RN of some product aggregating them). Otherwise, sure, 1) is the workaround solution to continue doing what we are doing.

Thanks, Eduard On Mon, Sep 19, 2016 at 8:21 PM, Vincent Massol <vincent(a)massol.net>

> wrote: >> >> We could have an "Extensions" section in the RN of XE where we could >> display noticeable functionalities. So that's your 1) variant. >> >> My problem is that we have this discrepancy between RN and

>> So this means we would duplicate content to RN and Documentation,

>> of reusing it. > > It’s not duplication. One explains the changes (the RN) and the other > explains the features. > > The RN should not duplicate too much of the ref documentation and it > should link to it. > > Of course there’s always a bit of overlap like screenshots (which btw we > don’t link since the screenshots in the ref doc change while they

> change over time on the RN page!). > > This could be a key reason that RN and reference doc could not be the > same! RN should not change so you can go back to it but reference doc

> keep being improved, screenshots updated, etc. Unless you always use a > revision number in your links/content and make sure to never loose the > history. > > Thanks > -Vincent > >> Usually instead of duplicating it, we just put it in one >> place and link from the other. Maybe the "News and Worthy" application >> could improve this. Have some ReleaseNotes objects per version that

>> be integrated inside XE RN and Extensions documentation, and use them > from >> the XE RN. >> >> Thanks, >> Caty >> >> On Mon, Sep 19, 2016 at 4:51 PM, Marius Dumitru Florea < >> mariusdumitru.florea(a)xwiki.com&gt; wrote: >> >>> +1 for 1) >>> >>> Thanks, >>> Marius >>> >>> On Tue, Sep 13, 2016 at 7:23 PM, Vincent Massol &lt;vincent(a)massol.net&gt; >>> wrote: >>> >>>> Hi devs, >>>> >>>> We now include a few contrib apps in XE. However, when someone checks > the >>>> RN for XE, for example http://www.xwiki.org/xwiki/ > bin/view/ReleaseNotes/ >>>> ReleaseNotesXWiki83M2 all they see is this: >>>> >>>> “The following dependencies have been upgraded: >>>> * Tour Application 1.0.4” >>>> >>>> It doesn’t say if there are any substantial things added those deps. >>>> >>>> I can think of 2 solutions: >>>> >>>> 1) When something is noticeable, add it to the RN of XE. So for

>>> if >>>> CKEditor extension adds something new, users checking the RN of XE

>>> see >>>> it immediately. >>>> >>>> 2) Link to the RN of the extension. However RN of extensions on e.x.o > are >>>> not nice. They’re just lists of JIRA issues. So for this solution to > be a >>>> bit satisfactory we would need to improve the RN of extensions, > starting >>>> with those we bundle in XE. Another possibility is to say that for >>>> Recommended Extensions we pay an extra care to write nice Release > Notes. >>>> But that’s harder to enforce and ensure. >>>> >>>> Option 1) is my preference. >>>> >>>> WDYT? >>>> >>>> Thanks >>>> -Vincent >