Re: [xwiki-devs] [Proposal] Release Notes Application

[Vincent Massol]

> On 23 Sep 2016, at 14:05, Vincent Massol  wrote:
> 
> Update of Friday 23rd of September:
> 
> * A first working version has been installed  on xwiki.org in the 
> ReleaeNotes2 space:
> http://www.xwiki.org/xwiki/bin/view/ReleaseNotes2
> 
> * The release notes for 8.3M1 has been completely converted to the new system:
> http://www.xwiki.org/xwiki/bin/view/ReleaseNotes2/Data/XWiki/83M1
> 
> * I’ll finish converting 8.3M2 and 8.3RC1 today

Done! You can see the RN on http://www.xwiki.org/xwiki/bin/view/ReleaseNotes2
This page also includes the aggregated release notes for 8.3 final (the New and 
Networthy part).

Thanks
-Vincent

> * @Devs: Could you start reviewing what I’ve done and see if it’s good enough 
> to start using it?  IMO it’s enough to get started. I’ll continue to improve 
> it (there are some small bugs that I know of like the LT filtering).
> 
> * Near Future: introduce a top level Release Notes app to have a LT on 
> ReleaseNotes2.WebHome with ability to create new RN pages. The idea is that 
> creating a new RN will generate a skeleton RN page and the "New And 
> Networthy” section will offer the ability to add new entries directly from 
> the RN page.
> 
> * Future: Once I’ve ironed out the problems and tuned the app to work as we 
> want it, I’ll export it on xwiki-contrib and continue developing it as an 
> extension.
> 
> * Further Future: Possibly merge this app with the Release Plan app and make 
> a global Release app which would have 2 concepts: Release plans (would be 
> optional) and Release Notes.
> 
> Does that sounds good? I’d really like that we start to use right now for the 
> 8.3RC1 release notes and to generate the final 8.3 release notes. 
> 
> Thanks
> -Vincent
> 
> 
>> On 16 Sep 2016, at 18:18, Vincent Massol  wrote:
>> 
>> Hi devs,
>> 
>> I’m planning to write a Release Notes Application for xwiki.org. I’d like to 
>> do something relatively simple in order to have a first working version.
>> 
>> Rationale
>> 
>> 
>> * Have nicer looking release notes by defining a structure and a common L
>> * For users, be able to see all the release notes item from a given version 
>> to another version and by category
>> 
>> Idea
>> 
>> 
>> Specifically for the “New and Networthy" section have:
>> - A visual that looks like this: https://www.jetbrains.com/datagrip/features/
>> - 2 columns layout
>> - For each item a screenshot and a summary text
>> - (optional) Have a “Learn more” button that goes to the item and provides 
>> more info (and possibly more screenshots if need be)
>> 
>> XProperties:
>> - Version (in which the item has been added). Static list
>> - Category (Help, Color Themes, Solr Search, AWM, etc). Static list
>> - Main screenshot 
>> - Summary text
>> - Additional content
>> - Target audience (User, Admin, Developer). Static list
>> 
>> Notes:
>> - If no “main screenshot” is provided then the generated report will put the 
>> item in a Miscellaneous section
>> 
>> For now I don’t want to handle other metadata for the releases notes, i.e. 
>> translations, upgrades, backward compat, tested browsers, etc). Precisely, 
>> I’m planning to write a “New and Networthy” application ATM, not a full 
>> “Release notes app”.
>> 
>> The way it could be used is through a {{news/}} macro, e.g.: {{news 
>> from=“6.4” to=“8.2” [categories=“help,awm,...”] 
>> [targetAudience=“user,admin”] /}}.
>> 
>> Usage
>> ==
>> 
>> - There would be a page in the wiki to see the livetable corresponding to 
>> all the release notes news (the xproperties above)
>> - Above this Livetable I imagine a form with several fields: 
>> — From version, 
>> — To Version 
>> — Category (if not empty generate the report only for that category)
>> — Target (user, admin, dev). (if not empty only generate the report for that 
>> target audience)
>> — + a “Generate” button to generate a dynamic "News and Networthy” report
>> - We would also use Tags for each news to categorize it further, e.g. 
>> “usability”, “performance”, and the LT would display the tag cloud. This 
>> will allow for example to see all items between such version and such 
>> version that are related to, say, performance
>> - We would still write a Release Notes page for each version but on that 
>> page, we would use the {{news/}} macro (with from = to = the version 
>> corresponding to that RN). On that page we would add all the other parts 
>> that are not in the app yet, i.e. translations, upgrades, backward compat, 
>> etc
>> - When an XWiki developers codes a new feature or improvement or new API 
>> will use the app to add it.
>> 
>> Future
>> ==
>> 
>> * Add a different release notes app to include the other metadata
>> * We could almost imagine using this “New and networthy” app to provide 
>> reference documentation for our features… :) (along with automatic “since”). 
>> That’s probably too science-fiction and I’m sure there are lots of gotchas 
>> but just mentioning 

Re: [xwiki-devs] [Proposal] Release Notes Application

[Vincent Massol]

Update of Friday 23rd of September:

* A first working version has been installed  on xwiki.org in the ReleaeNotes2 
space:
http://www.xwiki.org/xwiki/bin/view/ReleaseNotes2

* The release notes for 8.3M1 has been completely converted to the new system:
http://www.xwiki.org/xwiki/bin/view/ReleaseNotes2/Data/XWiki/83M1

* I’ll finish converting 8.3M2 and 8.3RC1 today

* @Devs: Could you start reviewing what I’ve done and see if it’s good enough 
to start using it?  IMO it’s enough to get started. I’ll continue to improve it 
(there are some small bugs that I know of like the LT filtering).

* Near Future: introduce a top level Release Notes app to have a LT on 
ReleaseNotes2.WebHome with ability to create new RN pages. The idea is that 
creating a new RN will generate a skeleton RN page and the "New And Networthy” 
section will offer the ability to add new entries directly from the RN page.

* Future: Once I’ve ironed out the problems and tuned the app to work as we 
want it, I’ll export it on xwiki-contrib and continue developing it as an 
extension.

* Further Future: Possibly merge this app with the Release Plan app and make a 
global Release app which would have 2 concepts: Release plans (would be 
optional) and Release Notes.

Does that sounds good? I’d really like that we start to use right now for the 
8.3RC1 release notes and to generate the final 8.3 release notes. 

Thanks
-Vincent


> On 16 Sep 2016, at 18:18, Vincent Massol  wrote:
> 
> Hi devs,
> 
> I’m planning to write a Release Notes Application for xwiki.org. I’d like to 
> do something relatively simple in order to have a first working version.
> 
> Rationale
> 
> 
> * Have nicer looking release notes by defining a structure and a common L
> * For users, be able to see all the release notes item from a given version 
> to another version and by category
> 
> Idea
> 
> 
> Specifically for the “New and Networthy" section have:
> - A visual that looks like this: https://www.jetbrains.com/datagrip/features/
> - 2 columns layout
> - For each item a screenshot and a summary text
> - (optional) Have a “Learn more” button that goes to the item and provides 
> more info (and possibly more screenshots if need be)
> 
> XProperties:
> - Version (in which the item has been added). Static list
> - Category (Help, Color Themes, Solr Search, AWM, etc). Static list
> - Main screenshot 
> - Summary text
> - Additional content
> - Target audience (User, Admin, Developer). Static list
> 
> Notes:
> - If no “main screenshot” is provided then the generated report will put the 
> item in a Miscellaneous section
> 
> For now I don’t want to handle other metadata for the releases notes, i.e. 
> translations, upgrades, backward compat, tested browsers, etc). Precisely, 
> I’m planning to write a “New and Networthy” application ATM, not a full 
> “Release notes app”.
> 
> The way it could be used is through a {{news/}} macro, e.g.: {{news 
> from=“6.4” to=“8.2” [categories=“help,awm,...”] [targetAudience=“user,admin”] 
> /}}.
> 
> Usage
> ==
> 
> - There would be a page in the wiki to see the livetable corresponding to all 
> the release notes news (the xproperties above)
> - Above this Livetable I imagine a form with several fields: 
> — From version, 
> — To Version 
> — Category (if not empty generate the report only for that category)
> — Target (user, admin, dev). (if not empty only generate the report for that 
> target audience)
> — + a “Generate” button to generate a dynamic "News and Networthy” report
> - We would also use Tags for each news to categorize it further, e.g. 
> “usability”, “performance”, and the LT would display the tag cloud. This will 
> allow for example to see all items between such version and such version that 
> are related to, say, performance
> - We would still write a Release Notes page for each version but on that 
> page, we would use the {{news/}} macro (with from = to = the version 
> corresponding to that RN). On that page we would add all the other parts that 
> are not in the app yet, i.e. translations, upgrades, backward compat, etc
> - When an XWiki developers codes a new feature or improvement or new API will 
> use the app to add it.
> 
> Future
> ==
> 
> * Add a different release notes app to include the other metadata
> * We could almost imagine using this “New and networthy” app to provide 
> reference documentation for our features… :) (along with automatic “since”). 
> That’s probably too science-fiction and I’m sure there are lots of gotchas 
> but just mentioning it here to make us dream a bit...
> 
> I’m starting to work on the POC. Let me know what you think.
> 
> Thanks
> -Vincent
> 

___
devs mailing list
devs@xwiki.org
http://lists.xwiki.org/mailman/listinfo/devs

Re: [xwiki-devs] [Proposal] Release Notes Application

[Vincent Massol]

Hi devs,

I’ve now uploaded the POC on xwiki.org so that you can test it and so that we 
can start using it/build on it.

It’s installed in the http://www.xwiki.org/xwiki/bin/view/ReleaseNotes2 space.

Two interesting links:

* The page listing the changes in a LT and allowing to add new changes: 
http://www.xwiki.org/xwiki/bin/view/ReleaseNotes2/Data/

* An example of the release notes for 8.3M1 using a 3 columns “Grid” displayer
http://www.xwiki.org/xwiki/bin/view/ReleaseNotes2/Data/XWiki/83M1/

(to use the flow displayer, use displayer=“flow” in the changes macro)

Thanks
-Vincent

> On 16 Sep 2016, at 18:18, Vincent Massol  wrote:
> 
> Hi devs,
> 
> I’m planning to write a Release Notes Application for xwiki.org. I’d like to 
> do something relatively simple in order to have a first working version.
> 
> Rationale
> 
> 
> * Have nicer looking release notes by defining a structure and a common L
> * For users, be able to see all the release notes item from a given version 
> to another version and by category
> 
> Idea
> 
> 
> Specifically for the “New and Networthy" section have:
> - A visual that looks like this: https://www.jetbrains.com/datagrip/features/
> - 2 columns layout
> - For each item a screenshot and a summary text
> - (optional) Have a “Learn more” button that goes to the item and provides 
> more info (and possibly more screenshots if need be)
> 
> XProperties:
> - Version (in which the item has been added). Static list
> - Category (Help, Color Themes, Solr Search, AWM, etc). Static list
> - Main screenshot 
> - Summary text
> - Additional content
> - Target audience (User, Admin, Developer). Static list
> 
> Notes:
> - If no “main screenshot” is provided then the generated report will put the 
> item in a Miscellaneous section
> 
> For now I don’t want to handle other metadata for the releases notes, i.e. 
> translations, upgrades, backward compat, tested browsers, etc). Precisely, 
> I’m planning to write a “New and Networthy” application ATM, not a full 
> “Release notes app”.
> 
> The way it could be used is through a {{news/}} macro, e.g.: {{news 
> from=“6.4” to=“8.2” [categories=“help,awm,...”] [targetAudience=“user,admin”] 
> /}}.
> 
> Usage
> ==
> 
> - There would be a page in the wiki to see the livetable corresponding to all 
> the release notes news (the xproperties above)
> - Above this Livetable I imagine a form with several fields: 
> — From version, 
> — To Version 
> — Category (if not empty generate the report only for that category)
> — Target (user, admin, dev). (if not empty only generate the report for that 
> target audience)
> — + a “Generate” button to generate a dynamic "News and Networthy” report
> - We would also use Tags for each news to categorize it further, e.g. 
> “usability”, “performance”, and the LT would display the tag cloud. This will 
> allow for example to see all items between such version and such version that 
> are related to, say, performance
> - We would still write a Release Notes page for each version but on that 
> page, we would use the {{news/}} macro (with from = to = the version 
> corresponding to that RN). On that page we would add all the other parts that 
> are not in the app yet, i.e. translations, upgrades, backward compat, etc
> - When an XWiki developers codes a new feature or improvement or new API will 
> use the app to add it.
> 
> Future
> ==
> 
> * Add a different release notes app to include the other metadata
> * We could almost imagine using this “New and networthy” app to provide 
> reference documentation for our features… :) (along with automatic “since”). 
> That’s probably too science-fiction and I’m sure there are lots of gotchas 
> but just mentioning it here to make us dream a bit...
> 
> I’m starting to work on the POC. Let me know what you think.
> 
> Thanks
> -Vincent
> 

___
devs mailing list
devs@xwiki.org
http://lists.xwiki.org/mailman/listinfo/devs

Re: [xwiki-devs] [Proposal] Release Notes Application

[Vincent Massol]

> On 20 Sep 2016, at 10:03, Guillaume Delhumeau  
> wrote:
> 
> 2016-09-19 18:52 GMT+02:00 Vincent Massol :
> 
>> 
>>> On 19 Sep 2016, at 16:02, Ecaterina Moraru (Valica) 
>> wrote:
>>> 
>>> Why don't we just improve this class
>>> http://extensions.xwiki.org/xwiki/bin/view/ExtensionCode/
>> ExtensionVersionClass
>>> ?
>> 
>> Because it’s very different! Actually there isn’t a single field that is
>> the same as my ChangesClass :)
>> 
>>> Maybe the difference is that this is per version and you kind of want per
>>> functionality.
>>> 
>>> But the 'Category' is not needed, since we have the extension page name.
>>> 
>>> The idea is that I would really want us to see if we could use this
>>> application also in the future, to document things for the extensions
>>> pages.
>> 
>> So, for this, I’ve added the notion of ‘Product” to the app.
> 
> 
> Can it takes multiple arguments? For instance, we develop 4 products:
> contrib, rendering, platform and enterprise.

Well I haven’t coded the filtering on product in the macro yet but we could 
imagine supporting a comma-separated list of product names yes.

Thanks
-Vincent

> So you can now use it for the release notes of any number of products (and
>> thus including for extensions with a separate versioning and release cycle).
>> 
>> We could imagine the extension page using the {{changes/}} macro to
>> display the RN, or point with a link to the RN page for that product (i.e.
>> extension).
>> 
>> Thanks
>> -Vincent
>> 
>>> Thanks,
>>> Caty
>> 
>> [snip]

___
devs mailing list
devs@xwiki.org
http://lists.xwiki.org/mailman/listinfo/devs

Re: [xwiki-devs] [Proposal] Release Notes Application

[Guillaume Delhumeau]

2016-09-19 18:52 GMT+02:00 Vincent Massol :

>
> > On 19 Sep 2016, at 16:02, Ecaterina Moraru (Valica) 
> wrote:
> >
> > Why don't we just improve this class
> > http://extensions.xwiki.org/xwiki/bin/view/ExtensionCode/
> ExtensionVersionClass
> > ?
>
> Because it’s very different! Actually there isn’t a single field that is
> the same as my ChangesClass :)
>
> > Maybe the difference is that this is per version and you kind of want per
> > functionality.
> >
> > But the 'Category' is not needed, since we have the extension page name.
> >
> > The idea is that I would really want us to see if we could use this
> > application also in the future, to document things for the extensions
> > pages.
>
> So, for this, I’ve added the notion of ‘Product” to the app.


Can it takes multiple arguments? For instance, we develop 4 products:
contrib, rendering, platform and enterprise.


> So you can now use it for the release notes of any number of products (and
> thus including for extensions with a separate versioning and release cycle).
>
> We could imagine the extension page using the {{changes/}} macro to
> display the RN, or point with a link to the RN page for that product (i.e.
> extension).
>
> Thanks
> -Vincent
>
> > Thanks,
> > Caty
>
> [snip]
>
> ___
> devs mailing list
> devs@xwiki.org
> http://lists.xwiki.org/mailman/listinfo/devs
>


Thanks,
-- 
Guillaume Delhumeau (guillaume.delhum...@xwiki.com)
Research & Development Engineer at XWiki SAS
Committer on the XWiki.org project
___
devs mailing list
devs@xwiki.org
http://lists.xwiki.org/mailman/listinfo/devs

Re: [xwiki-devs] [Proposal] Release Notes Application

[Vincent Massol]

> On 19 Sep 2016, at 16:02, Ecaterina Moraru (Valica)  wrote:
> 
> Why don't we just improve this class
> http://extensions.xwiki.org/xwiki/bin/view/ExtensionCode/ExtensionVersionClass
> ?

Because it’s very different! Actually there isn’t a single field that is the 
same as my ChangesClass :)

> Maybe the difference is that this is per version and you kind of want per
> functionality.
> 
> But the 'Category' is not needed, since we have the extension page name.
> 
> The idea is that I would really want us to see if we could use this
> application also in the future, to document things for the extensions
> pages.

So, for this, I’ve added the notion of ‘Product” to the app. So you can now use 
it for the release notes of any number of products (and thus including for 
extensions with a separate versioning and release cycle).

We could imagine the extension page using the {{changes/}} macro to display the 
RN, or point with a link to the RN page for that product (i.e. extension).

Thanks
-Vincent

> Thanks,
> Caty

[snip]

___
devs mailing list
devs@xwiki.org
http://lists.xwiki.org/mailman/listinfo/devs

Re: [xwiki-devs] [Proposal] Release Notes Application

[Vincent Massol]

> On 19 Sep 2016, at 14:13, Ecaterina Moraru (Valica)  wrote:

[snip]

>> Future
>> ==
>> 
>> * Add a different release notes app to include the other metadata
>> * We could almost imagine using this “New and networthy” app to provide
>> reference documentation for our features… :) (along with automatic
>> “since”). That’s probably too science-fiction and I’m sure there are lots
>> of gotchas but just mentioning it here to make us dream a bit...
>> 
> 
> I don't see how what you are proposing is any different from the Features
> documentation. Maybe this is the way to finally merge the documentation
> instead of having it spread in e.x.o and RNs. I guess the only difference
> is where we store the objects/pages.

This is what I was saying above ;) Except that it’s not so easy and is a much 
bigger scope. What I propose is to start with the Release Notes application, 
and as data fills up, we can start experimenting with using it to generate 
reference documentation. I think the main issue we’ll have is that adding up 
changes doesn't generate good documentation. It only generates a 
randomly-ordered list of features with no narrative.

In any case if we think it has value, we’ll be able to use it (and even 
possibly refactor the Release Notes app and extract a Features app from it). 

But let’s take it one step at a time!

> The release notes presents information
> for a particular version, while feature documentation presents information
> for a particular feature/category.

This is actually the same for both. They both present by category and version. 
For the reference documentation we use “Since XWiki N.NN” for the version info).

> We could use the same objects, with
> different parameters to display both RN and Documentation.
> 
> Regarding the inspiration for your proposal, I find their release notes to
> be more interesting
> https://www.jetbrains.com/datagrip/whatsnew/#language-injections

I’ve refactored the app I started to support multiple displayer. I now have 
Grid + Flow. You choose the displayer as a macro parameter:

{{changes … displayer=“flow” …/}}
{{changes … displayer=“grid” …/}}

> For example they provide the "categories navigation" at the top and also
> they group multiple functionalities for a particular category together,
> using subheaders.

Don’t forget that currently our Release notes don’t present just Features (what 
I call Changes). They also present updated libs, tested stuff, translations, 
backward compat, etc). So in order to have a top nav as on the link you gave 
above, you’ll need to refactor the RN page and probably extract out the Changes 
part from it.

Now I agree that for a user the main info are the Changes and we could change 
the design of our RN and focus on Changes and have a “Advanced” section at the 
end with the rest.

This is where we’d need your help :)

> I like what you did with the prototype. Unfortunately it's a bit hard to
> read and focus on reading the content: mostly because it's a bit crowded
> (with the 2/3 columns layout) and the dark gallery background is very
> distracting. But the styling can be fixed and the most important part are
> the app and metadata.

Yes, don’t worry you’ll have plenty of work to make it nice-looking ;)

> The idea to present as note in the Miscellaneous section if it doesn't have
> a screenshot is interesting. But we could also consider that we might want
> to have some small category summaries, where we list just the text, without
> any screenshots.

I’d really like to force having always screenshots for user-related changes. 
Anything too small to not have a screenshot is a misc for me. And I think we 
should do that since it would help us make sure that we always have screenshots 
for user-related changes.

> Or that we might want to showcase just the screenshots.

I don’t see how hard it is to add just a few words describing the screenshot.

Note that since the screenshots are metadata if you want a report showing only 
screenshots that’s easy to do.

> But this are just small observations and can be improved with display
> parameters.
> 
> Regarding importance, we need to be careful not to duplicate many things
> that we have in the jira issue.

Following Marius’s comment, I’ve added an “Importance” xproperty to the app 
(with 3 levels; High, Medium, Low). We’ll see how it goes.

> A wild idea would be to assign per
> functionality a jira issue and the app could extract metadata from there
> (the importance, the category, the version, etc.) But that's SF :)

Yes and I’m not even sure it’s a good thing since JIRA is a tool to help 
development (the importance of an issue in jira doesn’t correspond to the 
importance a feature has for users).

Thanks
-Vincent

> Nice work Vincent.
> 
> Thanks,
> Caty
> 
> 
> 
>> 
>> I’m starting to work on the POC. Let me know what you think.
>> 
>> Thanks
>> -Vincent
___
devs mailing list
devs@xwiki.org

Re: [xwiki-devs] [Proposal] Release Notes Application

[Ecaterina Moraru (Valica)]

I've re-read your answer about "The idea now is more that he release notes
should focus on summarizing the changes rather than documenting them.". In
this case instead of ExtensionFeatureClass, we could have something like
ExtensionFeatureSummaryClass or ExtensionFeatureHighlightClass. My only
point is that I don't understand why we would use a different application,
instead of extending the Repo app and keep all related things together (the
only problem is having too many objects for a particular page).

Thanks,
Caty

On Mon, Sep 19, 2016 at 5:24 PM, Ecaterina Moraru (Valica) <
vali...@gmail.com> wrote:

> If we extend the Repo app and create this ExtensionFeatureClass that
> contains all your XProperties (except Category) than we can include them
> easily in the RN and Documentation.
>
> We kind of have a "practice" to use something like "Since 8.3M2" (example
> in http://extensions.xwiki.org/xwiki/bin/view/Extension/
> Administration+Application) that could be generated from these types of
> objects, using different layouts depending if we are in RN or
> documentation.
>
> I'm stopping :) but the thing is that no matter how we implement the
> application is going to be useful to be able to filter
> features/versions/extension. So I'm excited to see it happen.
>
> Thanks,
> Caty
>
> On Mon, Sep 19, 2016 at 5:02 PM, Ecaterina Moraru (Valica) <
> vali...@gmail.com> wrote:
>
>> Why don't we just improve this class http://extensions.xwiki.org/xw
>> iki/bin/view/ExtensionCode/ExtensionVersionClass ?
>>
>> Maybe the difference is that this is per version and you kind of want per
>> functionality.
>>
>> But the 'Category' is not needed, since we have the extension page name.
>>
>> The idea is that I would really want us to see if we could use this
>> application also in the future, to document things for the extensions
>> pages.
>>
>> Thanks,
>> Caty
>>
>> On Mon, Sep 19, 2016 at 3:13 PM, Ecaterina Moraru (Valica) <
>> vali...@gmail.com> wrote:
>>
>>>
>>>
>>> On Fri, Sep 16, 2016 at 7:18 PM, Vincent Massol 
>>> wrote:
>>>
 Hi devs,

 I’m planning to write a Release Notes Application for xwiki.org. I’d
 like to do something relatively simple in order to have a first working
 version.

 Rationale
 

 * Have nicer looking release notes by defining a structure and a common
 L
 * For users, be able to see all the release notes item from a given
 version to another version and by category

 Idea
 

 Specifically for the “New and Networthy" section have:
 - A visual that looks like this: https://www.jetbrains.com/data
 grip/features/
 - 2 columns layout
 - For each item a screenshot and a summary text
 - (optional) Have a “Learn more” button that goes to the item and
 provides more info (and possibly more screenshots if need be)

 XProperties:
 - Version (in which the item has been added). Static list
 - Category (Help, Color Themes, Solr Search, AWM, etc). Static list
 - Main screenshot
 - Summary text
 - Additional content
 - Target audience (User, Admin, Developer). Static list

 Notes:
 - If no “main screenshot” is provided then the generated report will
 put the item in a Miscellaneous section

 For now I don’t want to handle other metadata for the releases notes,
 i.e. translations, upgrades, backward compat, tested browsers, etc).
 Precisely, I’m planning to write a “New and Networthy” application ATM, not
 a full “Release notes app”.

 The way it could be used is through a {{news/}} macro, e.g.: {{news
 from=“6.4” to=“8.2” [categories=“help,awm,...”]
 [targetAudience=“user,admin”] /}}.

 Usage
 ==

 - There would be a page in the wiki to see the livetable corresponding
 to all the release notes news (the xproperties above)
 - Above this Livetable I imagine a form with several fields:
 — From version,
 — To Version
 — Category (if not empty generate the report only for that category)
 — Target (user, admin, dev). (if not empty only generate the report for
 that target audience)
 — + a “Generate” button to generate a dynamic "News and Networthy”
 report
 - We would also use Tags for each news to categorize it further, e.g.
 “usability”, “performance”, and the LT would display the tag cloud. This
 will allow for example to see all items between such version and such
 version that are related to, say, performance
 - We would still write a Release Notes page for each version but on
 that page, we would use the {{news/}} macro (with from = to = the version
 corresponding to that RN). On that page we would add all the other parts
 that are not in the app yet, i.e. translations, upgrades, backward compat,
 etc
 - When an XWiki developers codes a new feature or improvement or new
 API will use the app to add 

Re: [xwiki-devs] [Proposal] Release Notes Application

[Ecaterina Moraru (Valica)]

If we extend the Repo app and create this ExtensionFeatureClass that
contains all your XProperties (except Category) than we can include them
easily in the RN and Documentation.

We kind of have a "practice" to use something like "Since 8.3M2" (example
in
http://extensions.xwiki.org/xwiki/bin/view/Extension/Administration+Application)
that could be generated from these types of objects, using different
layouts depending if we are in RN or documentation.

I'm stopping :) but the thing is that no matter how we implement the
application is going to be useful to be able to filter
features/versions/extension. So I'm excited to see it happen.

Thanks,
Caty

On Mon, Sep 19, 2016 at 5:02 PM, Ecaterina Moraru (Valica) <
vali...@gmail.com> wrote:

> Why don't we just improve this class http://extensions.xwiki.org/
> xwiki/bin/view/ExtensionCode/ExtensionVersionClass ?
>
> Maybe the difference is that this is per version and you kind of want per
> functionality.
>
> But the 'Category' is not needed, since we have the extension page name.
>
> The idea is that I would really want us to see if we could use this
> application also in the future, to document things for the extensions
> pages.
>
> Thanks,
> Caty
>
> On Mon, Sep 19, 2016 at 3:13 PM, Ecaterina Moraru (Valica) <
> vali...@gmail.com> wrote:
>
>>
>>
>> On Fri, Sep 16, 2016 at 7:18 PM, Vincent Massol 
>> wrote:
>>
>>> Hi devs,
>>>
>>> I’m planning to write a Release Notes Application for xwiki.org. I’d
>>> like to do something relatively simple in order to have a first working
>>> version.
>>>
>>> Rationale
>>> 
>>>
>>> * Have nicer looking release notes by defining a structure and a common
>>> L
>>> * For users, be able to see all the release notes item from a given
>>> version to another version and by category
>>>
>>> Idea
>>> 
>>>
>>> Specifically for the “New and Networthy" section have:
>>> - A visual that looks like this: https://www.jetbrains.com/data
>>> grip/features/
>>> - 2 columns layout
>>> - For each item a screenshot and a summary text
>>> - (optional) Have a “Learn more” button that goes to the item and
>>> provides more info (and possibly more screenshots if need be)
>>>
>>> XProperties:
>>> - Version (in which the item has been added). Static list
>>> - Category (Help, Color Themes, Solr Search, AWM, etc). Static list
>>> - Main screenshot
>>> - Summary text
>>> - Additional content
>>> - Target audience (User, Admin, Developer). Static list
>>>
>>> Notes:
>>> - If no “main screenshot” is provided then the generated report will put
>>> the item in a Miscellaneous section
>>>
>>> For now I don’t want to handle other metadata for the releases notes,
>>> i.e. translations, upgrades, backward compat, tested browsers, etc).
>>> Precisely, I’m planning to write a “New and Networthy” application ATM, not
>>> a full “Release notes app”.
>>>
>>> The way it could be used is through a {{news/}} macro, e.g.: {{news
>>> from=“6.4” to=“8.2” [categories=“help,awm,...”]
>>> [targetAudience=“user,admin”] /}}.
>>>
>>> Usage
>>> ==
>>>
>>> - There would be a page in the wiki to see the livetable corresponding
>>> to all the release notes news (the xproperties above)
>>> - Above this Livetable I imagine a form with several fields:
>>> — From version,
>>> — To Version
>>> — Category (if not empty generate the report only for that category)
>>> — Target (user, admin, dev). (if not empty only generate the report for
>>> that target audience)
>>> — + a “Generate” button to generate a dynamic "News and Networthy” report
>>> - We would also use Tags for each news to categorize it further, e.g.
>>> “usability”, “performance”, and the LT would display the tag cloud. This
>>> will allow for example to see all items between such version and such
>>> version that are related to, say, performance
>>> - We would still write a Release Notes page for each version but on that
>>> page, we would use the {{news/}} macro (with from = to = the version
>>> corresponding to that RN). On that page we would add all the other parts
>>> that are not in the app yet, i.e. translations, upgrades, backward compat,
>>> etc
>>> - When an XWiki developers codes a new feature or improvement or new API
>>> will use the app to add it.
>>>
>>> Future
>>> ==
>>>
>>> * Add a different release notes app to include the other metadata
>>> * We could almost imagine using this “New and networthy” app to provide
>>> reference documentation for our features… :) (along with automatic
>>> “since”). That’s probably too science-fiction and I’m sure there are lots
>>> of gotchas but just mentioning it here to make us dream a bit...
>>>
>>
>> I don't see how what you are proposing is any different from the Features
>> documentation. Maybe this is the way to finally merge the documentation
>> instead of having it spread in e.x.o and RNs. I guess the only difference
>> is where we store the objects/pages. The release notes presents information
>> for a particular version, 

Re: [xwiki-devs] [Proposal] Release Notes Application

[Ecaterina Moraru (Valica)]

Why don't we just improve this class
http://extensions.xwiki.org/xwiki/bin/view/ExtensionCode/ExtensionVersionClass
?

Maybe the difference is that this is per version and you kind of want per
functionality.

But the 'Category' is not needed, since we have the extension page name.

The idea is that I would really want us to see if we could use this
application also in the future, to document things for the extensions
pages.

Thanks,
Caty

On Mon, Sep 19, 2016 at 3:13 PM, Ecaterina Moraru (Valica) <
vali...@gmail.com> wrote:

>
>
> On Fri, Sep 16, 2016 at 7:18 PM, Vincent Massol 
> wrote:
>
>> Hi devs,
>>
>> I’m planning to write a Release Notes Application for xwiki.org. I’d
>> like to do something relatively simple in order to have a first working
>> version.
>>
>> Rationale
>> 
>>
>> * Have nicer looking release notes by defining a structure and a common
>> L
>> * For users, be able to see all the release notes item from a given
>> version to another version and by category
>>
>> Idea
>> 
>>
>> Specifically for the “New and Networthy" section have:
>> - A visual that looks like this: https://www.jetbrains.com/data
>> grip/features/
>> - 2 columns layout
>> - For each item a screenshot and a summary text
>> - (optional) Have a “Learn more” button that goes to the item and
>> provides more info (and possibly more screenshots if need be)
>>
>> XProperties:
>> - Version (in which the item has been added). Static list
>> - Category (Help, Color Themes, Solr Search, AWM, etc). Static list
>> - Main screenshot
>> - Summary text
>> - Additional content
>> - Target audience (User, Admin, Developer). Static list
>>
>> Notes:
>> - If no “main screenshot” is provided then the generated report will put
>> the item in a Miscellaneous section
>>
>> For now I don’t want to handle other metadata for the releases notes,
>> i.e. translations, upgrades, backward compat, tested browsers, etc).
>> Precisely, I’m planning to write a “New and Networthy” application ATM, not
>> a full “Release notes app”.
>>
>> The way it could be used is through a {{news/}} macro, e.g.: {{news
>> from=“6.4” to=“8.2” [categories=“help,awm,...”]
>> [targetAudience=“user,admin”] /}}.
>>
>> Usage
>> ==
>>
>> - There would be a page in the wiki to see the livetable corresponding to
>> all the release notes news (the xproperties above)
>> - Above this Livetable I imagine a form with several fields:
>> — From version,
>> — To Version
>> — Category (if not empty generate the report only for that category)
>> — Target (user, admin, dev). (if not empty only generate the report for
>> that target audience)
>> — + a “Generate” button to generate a dynamic "News and Networthy” report
>> - We would also use Tags for each news to categorize it further, e.g.
>> “usability”, “performance”, and the LT would display the tag cloud. This
>> will allow for example to see all items between such version and such
>> version that are related to, say, performance
>> - We would still write a Release Notes page for each version but on that
>> page, we would use the {{news/}} macro (with from = to = the version
>> corresponding to that RN). On that page we would add all the other parts
>> that are not in the app yet, i.e. translations, upgrades, backward compat,
>> etc
>> - When an XWiki developers codes a new feature or improvement or new API
>> will use the app to add it.
>>
>> Future
>> ==
>>
>> * Add a different release notes app to include the other metadata
>> * We could almost imagine using this “New and networthy” app to provide
>> reference documentation for our features… :) (along with automatic
>> “since”). That’s probably too science-fiction and I’m sure there are lots
>> of gotchas but just mentioning it here to make us dream a bit...
>>
>
> I don't see how what you are proposing is any different from the Features
> documentation. Maybe this is the way to finally merge the documentation
> instead of having it spread in e.x.o and RNs. I guess the only difference
> is where we store the objects/pages. The release notes presents information
> for a particular version, while feature documentation presents information
> for a particular feature/category. We could use the same objects, with
> different parameters to display both RN and Documentation.
>
> Regarding the inspiration for your proposal, I find their release notes to
> be more interesting https://www.jetbrains.com/datagrip/whatsnew/#language-
> injections
> For example they provide the "categories navigation" at the top and also
> they group multiple functionalities for a particular category together,
> using subheaders.
>
> I like what you did with the prototype. Unfortunately it's a bit hard to
> read and focus on reading the content: mostly because it's a bit crowded
> (with the 2/3 columns layout) and the dark gallery background is very
> distracting. But the styling can be fixed and the most important part are
> the app and metadata.
>
> The idea to present as 

Re: [xwiki-devs] [Proposal] Release Notes Application

[Ecaterina Moraru (Valica)]

On Fri, Sep 16, 2016 at 7:18 PM, Vincent Massol  wrote:

> Hi devs,
>
> I’m planning to write a Release Notes Application for xwiki.org. I’d like
> to do something relatively simple in order to have a first working version.
>
> Rationale
> 
>
> * Have nicer looking release notes by defining a structure and a common L
> * For users, be able to see all the release notes item from a given
> version to another version and by category
>
> Idea
> 
>
> Specifically for the “New and Networthy" section have:
> - A visual that looks like this: https://www.jetbrains.com/
> datagrip/features/
> - 2 columns layout
> - For each item a screenshot and a summary text
> - (optional) Have a “Learn more” button that goes to the item and provides
> more info (and possibly more screenshots if need be)
>
> XProperties:
> - Version (in which the item has been added). Static list
> - Category (Help, Color Themes, Solr Search, AWM, etc). Static list
> - Main screenshot
> - Summary text
> - Additional content
> - Target audience (User, Admin, Developer). Static list
>
> Notes:
> - If no “main screenshot” is provided then the generated report will put
> the item in a Miscellaneous section
>
> For now I don’t want to handle other metadata for the releases notes, i.e.
> translations, upgrades, backward compat, tested browsers, etc). Precisely,
> I’m planning to write a “New and Networthy” application ATM, not a full
> “Release notes app”.
>
> The way it could be used is through a {{news/}} macro, e.g.: {{news
> from=“6.4” to=“8.2” [categories=“help,awm,...”]
> [targetAudience=“user,admin”] /}}.
>
> Usage
> ==
>
> - There would be a page in the wiki to see the livetable corresponding to
> all the release notes news (the xproperties above)
> - Above this Livetable I imagine a form with several fields:
> — From version,
> — To Version
> — Category (if not empty generate the report only for that category)
> — Target (user, admin, dev). (if not empty only generate the report for
> that target audience)
> — + a “Generate” button to generate a dynamic "News and Networthy” report
> - We would also use Tags for each news to categorize it further, e.g.
> “usability”, “performance”, and the LT would display the tag cloud. This
> will allow for example to see all items between such version and such
> version that are related to, say, performance
> - We would still write a Release Notes page for each version but on that
> page, we would use the {{news/}} macro (with from = to = the version
> corresponding to that RN). On that page we would add all the other parts
> that are not in the app yet, i.e. translations, upgrades, backward compat,
> etc
> - When an XWiki developers codes a new feature or improvement or new API
> will use the app to add it.
>
> Future
> ==
>
> * Add a different release notes app to include the other metadata
> * We could almost imagine using this “New and networthy” app to provide
> reference documentation for our features… :) (along with automatic
> “since”). That’s probably too science-fiction and I’m sure there are lots
> of gotchas but just mentioning it here to make us dream a bit...
>

I don't see how what you are proposing is any different from the Features
documentation. Maybe this is the way to finally merge the documentation
instead of having it spread in e.x.o and RNs. I guess the only difference
is where we store the objects/pages. The release notes presents information
for a particular version, while feature documentation presents information
for a particular feature/category. We could use the same objects, with
different parameters to display both RN and Documentation.

Regarding the inspiration for your proposal, I find their release notes to
be more interesting
https://www.jetbrains.com/datagrip/whatsnew/#language-injections
For example they provide the "categories navigation" at the top and also
they group multiple functionalities for a particular category together,
using subheaders.

I like what you did with the prototype. Unfortunately it's a bit hard to
read and focus on reading the content: mostly because it's a bit crowded
(with the 2/3 columns layout) and the dark gallery background is very
distracting. But the styling can be fixed and the most important part are
the app and metadata.

The idea to present as note in the Miscellaneous section if it doesn't have
a screenshot is interesting. But we could also consider that we might want
to have some small category summaries, where we list just the text, without
any screenshots. Or that we might want to showcase just the screenshots.
But this are just small observations and can be improved with display
parameters.

Regarding importance, we need to be careful not to duplicate many things
that we have in the jira issue. A wild idea would be to assign per
functionality a jira issue and the app could extract metadata from there
(the importance, the category, the version, etc.) But that's SF :)

Nice work Vincent.

Re: [xwiki-devs] [Proposal] Release Notes Application

[Vincent Massol]

Hi Marius;

> On 19 Sep 2016, at 13:46, Marius Dumitru Florea 
>  wrote:
> 
> On Sat, Sep 17, 2016 at 6:29 PM, Vincent Massol  wrote:
> 
>> Hi again,
>> 
>> Done more coding (in front of the TV watching the Tennis David cup :
>> France vs Croatia ;))...
>> 
>> I’ve now completely rewritten the 8.3M1 release notes using the release
>> notes app:
>> https://www.evernote.com/l/AHc8Tp-XK6VMkY8ZL0YnNuEg7XLUavZliKM
>> 
>> FTR changes I’ve brought:
>> * In the end, "When the target audience is “developer” the screenshot is
>> replaced by an example.” was not a good idea and I’ve dropped it.
>> * For the developers section, I’ve used a single column view. FTR here’s
>> the wiki syntax for the New and Networthy part:
>> 
>> "
>> = New and Noteworthy (since XWiki 8.2) =
>> 
>> [[Full list of issues fixed and Dashboard for 8.3>>http://jira.xwiki.org/
>> secure/Dashboard.jspa?selectPageId=13629]].
>> 
>> == For Users ==
>> 
>> {{news columns="3" audience="user"/}}
>> 
>> == For Admins ==
>> 
>> {{news columns="3" audience="administrator"/}}
>> 
>> == For Developers ==
>> 
>> {{news columns="1" audience="developer"/}}
>> “
>> 
>> 
> 
>> I’m quite happy about the result. Do you like it too?
>> 
> 
> The release page layout should be responsive or at least it should look
> nice on a small screen. Hard-coding the 3-column layout is not nice.

I’m using bootstrap grids. We can tune that but it should already be responsive.

> The black background color of the gallery macro works when you have a
> single gallery, but in your case I feel it distracts the view.

The gallery should be a lot more configurable:
* Ability to set maxWdith/maxHeight
* Ability to set the background color
* Ability to not display navigation arrows and image number when there’s only 1 
image

> I assume you group the new features by category,

I don’t yet (but would be a good idea). I’m grouping by Audience only (user, 
admin, dev).

> but what about the order
> between the categories and inside each category. We want to push the most
> important features/categories first.

It’s a complex topic and I’m not sure sure we need it. The column layout I’ve 
shown allows to display a lot more changes than before. It’s also a change of 
spirit. The idea now is more that he release notes should focus on summarizing 
the changes rather than documenting them. It happens that we put too much in 
the release notes when the changes should be documented in the reference 
documentation. I think we only need a summary and then point to the reference 
documentation for more details.

What I mean is that I feel that the order is less important if the user can see 
at a glance all the changes in a more structured and visible way.

In addition the importance is relative. An item can be very important for a 
given release note but less important when put next to other changes from 
previous release notes. Said differently, if I ask for all changes from XWiki 
7.0 to XWiki 7.4, the importance order will definitely be different from the 
order for, say, XWiki 7.2.

So I’d say, let’s try without order first and see if we really need to define 
an order in the structure.

Now what we could do that would make sense I think is a global indication of 
the level of importance with 2 levels:
* High importance (new features, large improvements)
* Small importance (cosmetic changes, small improvements)

> Also, when there are many (small) new features it may be good to visually
> mark their category (or separate each category, like the headings we have
> know) because someone reading the release notes may be interested only in a
> specific topic (e.g. Solr changes).

That’s the point, the app allows you to generate a report of whatever you’re 
interested in. I dissociate 2 things:
* The Release Notes. Which is fixed and contains changes + other information 
(backward compat, translations, etc)
* The Changes App, which allows to generate all the changes from version N to 
version P, for category C, for target audience T. So you can ask: show me all 
changes in XWiki 8.3M1 related to Solr. In the future I’d like to add support 
for asking for specific tags too to be able to ask for all performance-related 
changes too. Note that the Category data could also be implemented in the same 
way I guess but FTM it’s implemented as an xproperty.

What we could do is display some tags displayed as labels under the change 
titles.

> Plus, it may be hard to understand from
> the title that a specific new feature is related to a specific topic
> (category), especially when you scan the release notes quickly in search
> for something (the Table of Contents is useful for this).
> 
> +1 for adding more structure to the release notes.

Thanks for the feedback. There are plenty of things to do and tune. I want to 
get started.

Note: I also want to be careful about not adding too much structure since too 
much metadata means you need to fill it and 

Re: [xwiki-devs] [Proposal] Release Notes Application

[Marius Dumitru Florea]

On Sat, Sep 17, 2016 at 6:29 PM, Vincent Massol  wrote:

> Hi again,
>
> Done more coding (in front of the TV watching the Tennis David cup :
> France vs Croatia ;))...
>
> I’ve now completely rewritten the 8.3M1 release notes using the release
> notes app:
> https://www.evernote.com/l/AHc8Tp-XK6VMkY8ZL0YnNuEg7XLUavZliKM
>
> FTR changes I’ve brought:
> * In the end, "When the target audience is “developer” the screenshot is
> replaced by an example.” was not a good idea and I’ve dropped it.
> * For the developers section, I’ve used a single column view. FTR here’s
> the wiki syntax for the New and Networthy part:
>
> "
> = New and Noteworthy (since XWiki 8.2) =
>
> [[Full list of issues fixed and Dashboard for 8.3>>http://jira.xwiki.org/
> secure/Dashboard.jspa?selectPageId=13629]].
>
> == For Users ==
>
> {{news columns="3" audience="user"/}}
>
> == For Admins ==
>
> {{news columns="3" audience="administrator"/}}
>
> == For Developers ==
>
> {{news columns="1" audience="developer"/}}
> “
>
>

> I’m quite happy about the result. Do you like it too?
>

The release page layout should be responsive or at least it should look
nice on a small screen. Hard-coding the 3-column layout is not nice.

The black background color of the gallery macro works when you have a
single gallery, but in your case I feel it distracts the view.

I assume you group the new features by category, but what about the order
between the categories and inside each category. We want to push the most
important features/categories first.

Also, when there are many (small) new features it may be good to visually
mark their category (or separate each category, like the headings we have
know) because someone reading the release notes may be interested only in a
specific topic (e.g. Solr changes). Plus, it may be hard to understand from
the title that a specific new feature is related to a specific topic
(category), especially when you scan the release notes quickly in search
for something (the Table of Contents is useful for this).

+1 for adding more structure to the release notes.

Thanks,
Marius


>
> Next step: Provide a UI for adding a release notes news (right now I’ve
> used the object editor to write the RN for 8.3M1).
>
> Thanks
> -Vincent
>
>
> > On 17 Sep 2016, at 12:27, Vincent Massol  wrote:
> >
> > I’ve done a quick POC locally, if you’re curious:
> >
> > * 3 columns view (using {{news columns=“3”/}}:
> > https://www.evernote.com/l/AHcrwTDtWzBL7JaGLsTvj3NcP95dEYwraOc
> >
> > * 2 columns view (using {{news columns=“2"/}}:
> > https://www.evernote.com/l/AHche7VWkv1KgLZPkWqbVv_ZGn728y-tAzw
> >
> > * Livetable view of data:
> > https://www.evernote.com/l/AHcItOb57M9AMIaU6HXBTO04c3o91dVKck4
> >
> > Note1: I’ve added a title xproperty too.
> > Note2: I’ve tweaked a bit the CSS of the galley macro but I could commit
> this (see http://extensions.xwiki.org/xwiki/bin/view/Extension/
> Gallery+Macro?viewer=comments#xwikicomment_6). I’ll also need to talk to
> marius about the 128px padding for left/right arrows (which I’ve reduced to
> 45px for the screenshots above).
> >
> > Thanks
> > -Vincent
> >
> >> On 16 Sep 2016, at 18:18, Vincent Massol  wrote:
> >>
> >> Hi devs,
> >>
> >> I’m planning to write a Release Notes Application for xwiki.org. I’d
> like to do something relatively simple in order to have a first working
> version.
> >>
> >> Rationale
> >> 
> >>
> >> * Have nicer looking release notes by defining a structure and a common
> L
> >> * For users, be able to see all the release notes item from a given
> version to another version and by category
> >>
> >> Idea
> >> 
> >>
> >> Specifically for the “New and Networthy" section have:
> >> - A visual that looks like this: https://www.jetbrains.com/
> datagrip/features/
> >> - 2 columns layout
> >> - For each item a screenshot and a summary text
> >> - (optional) Have a “Learn more” button that goes to the item and
> provides more info (and possibly more screenshots if need be)
> >>
> >> XProperties:
> >> - Version (in which the item has been added). Static list
> >> - Category (Help, Color Themes, Solr Search, AWM, etc). Static list
> >> - Main screenshot
> >> - Summary text
> >> - Additional content
> >> - Target audience (User, Admin, Developer). Static list
> >>
> >> Notes:
> >> - If no “main screenshot” is provided then the generated report will
> put the item in a Miscellaneous section
> >>
> >> For now I don’t want to handle other metadata for the releases notes,
> i.e. translations, upgrades, backward compat, tested browsers, etc).
> Precisely, I’m planning to write a “New and Networthy” application ATM, not
> a full “Release notes app”.
> >>
> >> The way it could be used is through a {{news/}} macro, e.g.: {{news
> from=“6.4” to=“8.2” [categories=“help,awm,...”]
> [targetAudience=“user,admin”] /}}.
> >>
> >> Usage
> >> ==
> >>
> >> - There would be a page in the wiki to see the livetable 

Re: [xwiki-devs] [Proposal] Release Notes Application

[Benjamin Lanciaux]

Hello Vincent,

I'm +1 with your proposal. It will ease the comparisons of the different
versions.
It also goes beyond the simple wiki page by adding some structure to it.
This is what XWiki is good at after all ;)

Thanks,

Benjamin



2016-09-17 17:38 GMT+02:00 Vincent Massol :

> If you wish to compare with the current RN:
> http://www.xwiki.org/xwiki/bin/view/ReleaseNotes/ReleaseNotesXWiki83M1
>
> I personally don’t find it worse. It actually looks even a bit better IMO.
>
> But the pros are not really for this. It’s that now you can do lots of
> reports:
> * See all release notes news for all versions from N to P
> * And only for user-related features
> * Or only for a given module/application. For ex: show me all the changes
> related to SOLR from XWiki 6.1 to XWiki 8.2.
>
> Thanks
> -Vincent
>
> > On 17 Sep 2016, at 17:29, Vincent Massol  wrote:
> >
> > Hi again,
> >
> > Done more coding (in front of the TV watching the Tennis David cup :
> France vs Croatia ;))...
> >
> > I’ve now completely rewritten the 8.3M1 release notes using the release
> notes app:
> > https://www.evernote.com/l/AHc8Tp-XK6VMkY8ZL0YnNuEg7XLUavZliKM
> >
> > FTR changes I’ve brought:
> > * In the end, "When the target audience is “developer” the screenshot is
> replaced by an example.” was not a good idea and I’ve dropped it.
> > * For the developers section, I’ve used a single column view. FTR here’s
> the wiki syntax for the New and Networthy part:
> >
> > "
> > = New and Noteworthy (since XWiki 8.2) =
> >
> > [[Full list of issues fixed and Dashboard for 8.3>>
> http://jira.xwiki.org/secure/Dashboard.jspa?selectPageId=13629]].
> >
> > == For Users ==
> >
> > {{news columns="3" audience="user"/}}
> >
> > == For Admins ==
> >
> > {{news columns="3" audience="administrator"/}}
> >
> > == For Developers ==
> >
> > {{news columns="1" audience="developer"/}}
> > “
> >
> > I’m quite happy about the result. Do you like it too?
> >
> > Next step: Provide a UI for adding a release notes news (right now I’ve
> used the object editor to write the RN for 8.3M1).
> >
> > Thanks
> > -Vincent
> >
> >
> >> On 17 Sep 2016, at 12:27, Vincent Massol  wrote:
> >>
> >> I’ve done a quick POC locally, if you’re curious:
> >>
> >> * 3 columns view (using {{news columns=“3”/}}:
> >> https://www.evernote.com/l/AHcrwTDtWzBL7JaGLsTvj3NcP95dEYwraOc
> >>
> >> * 2 columns view (using {{news columns=“2"/}}:
> >> https://www.evernote.com/l/AHche7VWkv1KgLZPkWqbVv_ZGn728y-tAzw
> >>
> >> * Livetable view of data:
> >> https://www.evernote.com/l/AHcItOb57M9AMIaU6HXBTO04c3o91dVKck4
> >>
> >> Note1: I’ve added a title xproperty too.
> >> Note2: I’ve tweaked a bit the CSS of the galley macro but I could
> commit this (see http://extensions.xwiki.org/xwiki/bin/view/Extension/
> Gallery+Macro?viewer=comments#xwikicomment_6). I’ll also need to talk to
> marius about the 128px padding for left/right arrows (which I’ve reduced to
> 45px for the screenshots above).
> >>
> >> Thanks
> >> -Vincent
> >>
> >>> On 16 Sep 2016, at 18:18, Vincent Massol  wrote:
> >>>
> >>> Hi devs,
> >>>
> >>> I’m planning to write a Release Notes Application for xwiki.org. I’d
> like to do something relatively simple in order to have a first working
> version.
> >>>
> >>> Rationale
> >>> 
> >>>
> >>> * Have nicer looking release notes by defining a structure and a
> common L
> >>> * For users, be able to see all the release notes item from a given
> version to another version and by category
> >>>
> >>> Idea
> >>> 
> >>>
> >>> Specifically for the “New and Networthy" section have:
> >>> - A visual that looks like this: https://www.jetbrains.com/
> datagrip/features/
> >>> - 2 columns layout
> >>> - For each item a screenshot and a summary text
> >>> - (optional) Have a “Learn more” button that goes to the item and
> provides more info (and possibly more screenshots if need be)
> >>>
> >>> XProperties:
> >>> - Version (in which the item has been added). Static list
> >>> - Category (Help, Color Themes, Solr Search, AWM, etc). Static list
> >>> - Main screenshot
> >>> - Summary text
> >>> - Additional content
> >>> - Target audience (User, Admin, Developer). Static list
> >>>
> >>> Notes:
> >>> - If no “main screenshot” is provided then the generated report will
> put the item in a Miscellaneous section
> >>>
> >>> For now I don’t want to handle other metadata for the releases notes,
> i.e. translations, upgrades, backward compat, tested browsers, etc).
> Precisely, I’m planning to write a “New and Networthy” application ATM, not
> a full “Release notes app”.
> >>>
> >>> The way it could be used is through a {{news/}} macro, e.g.: {{news
> from=“6.4” to=“8.2” [categories=“help,awm,...”]
> [targetAudience=“user,admin”] /}}.
> >>>
> >>> Usage
> >>> ==
> >>>
> >>> - There would be a page in the wiki to see the livetable corresponding
> to all the release notes news (the xproperties above)
> >>> - Above 

Re: [xwiki-devs] [Proposal] Release Notes Application

[Vincent Massol]

If you wish to compare with the current RN:
http://www.xwiki.org/xwiki/bin/view/ReleaseNotes/ReleaseNotesXWiki83M1

I personally don’t find it worse. It actually looks even a bit better IMO.

But the pros are not really for this. It’s that now you can do lots of reports:
* See all release notes news for all versions from N to P
* And only for user-related features
* Or only for a given module/application. For ex: show me all the changes 
related to SOLR from XWiki 6.1 to XWiki 8.2.

Thanks
-Vincent

> On 17 Sep 2016, at 17:29, Vincent Massol  wrote:
> 
> Hi again,
> 
> Done more coding (in front of the TV watching the Tennis David cup : France 
> vs Croatia ;))...
> 
> I’ve now completely rewritten the 8.3M1 release notes using the release notes 
> app:
> https://www.evernote.com/l/AHc8Tp-XK6VMkY8ZL0YnNuEg7XLUavZliKM
> 
> FTR changes I’ve brought:
> * In the end, "When the target audience is “developer” the screenshot is 
> replaced by an example.” was not a good idea and I’ve dropped it.
> * For the developers section, I’ve used a single column view. FTR here’s the 
> wiki syntax for the New and Networthy part:
> 
> "
> = New and Noteworthy (since XWiki 8.2) =
> 
> [[Full list of issues fixed and Dashboard for 
> 8.3>>http://jira.xwiki.org/secure/Dashboard.jspa?selectPageId=13629]].
> 
> == For Users ==
> 
> {{news columns="3" audience="user"/}}
> 
> == For Admins ==
> 
> {{news columns="3" audience="administrator"/}}
> 
> == For Developers ==
> 
> {{news columns="1" audience="developer"/}}
> “
> 
> I’m quite happy about the result. Do you like it too?
> 
> Next step: Provide a UI for adding a release notes news (right now I’ve used 
> the object editor to write the RN for 8.3M1).
> 
> Thanks
> -Vincent
> 
> 
>> On 17 Sep 2016, at 12:27, Vincent Massol  wrote:
>> 
>> I’ve done a quick POC locally, if you’re curious:
>> 
>> * 3 columns view (using {{news columns=“3”/}}:
>> https://www.evernote.com/l/AHcrwTDtWzBL7JaGLsTvj3NcP95dEYwraOc
>> 
>> * 2 columns view (using {{news columns=“2"/}}:
>> https://www.evernote.com/l/AHche7VWkv1KgLZPkWqbVv_ZGn728y-tAzw
>> 
>> * Livetable view of data:
>> https://www.evernote.com/l/AHcItOb57M9AMIaU6HXBTO04c3o91dVKck4
>> 
>> Note1: I’ve added a title xproperty too.
>> Note2: I’ve tweaked a bit the CSS of the galley macro but I could commit 
>> this (see 
>> http://extensions.xwiki.org/xwiki/bin/view/Extension/Gallery+Macro?viewer=comments#xwikicomment_6).
>>  I’ll also need to talk to marius about the 128px padding for left/right 
>> arrows (which I’ve reduced to 45px for the screenshots above). 
>> 
>> Thanks
>> -Vincent
>> 
>>> On 16 Sep 2016, at 18:18, Vincent Massol  wrote:
>>> 
>>> Hi devs,
>>> 
>>> I’m planning to write a Release Notes Application for xwiki.org. I’d like 
>>> to do something relatively simple in order to have a first working version.
>>> 
>>> Rationale
>>> 
>>> 
>>> * Have nicer looking release notes by defining a structure and a common L
>>> * For users, be able to see all the release notes item from a given version 
>>> to another version and by category
>>> 
>>> Idea
>>> 
>>> 
>>> Specifically for the “New and Networthy" section have:
>>> - A visual that looks like this: 
>>> https://www.jetbrains.com/datagrip/features/
>>> - 2 columns layout
>>> - For each item a screenshot and a summary text
>>> - (optional) Have a “Learn more” button that goes to the item and provides 
>>> more info (and possibly more screenshots if need be)
>>> 
>>> XProperties:
>>> - Version (in which the item has been added). Static list
>>> - Category (Help, Color Themes, Solr Search, AWM, etc). Static list
>>> - Main screenshot 
>>> - Summary text
>>> - Additional content
>>> - Target audience (User, Admin, Developer). Static list
>>> 
>>> Notes:
>>> - If no “main screenshot” is provided then the generated report will put 
>>> the item in a Miscellaneous section
>>> 
>>> For now I don’t want to handle other metadata for the releases notes, i.e. 
>>> translations, upgrades, backward compat, tested browsers, etc). Precisely, 
>>> I’m planning to write a “New and Networthy” application ATM, not a full 
>>> “Release notes app”.
>>> 
>>> The way it could be used is through a {{news/}} macro, e.g.: {{news 
>>> from=“6.4” to=“8.2” [categories=“help,awm,...”] 
>>> [targetAudience=“user,admin”] /}}.
>>> 
>>> Usage
>>> ==
>>> 
>>> - There would be a page in the wiki to see the livetable corresponding to 
>>> all the release notes news (the xproperties above)
>>> - Above this Livetable I imagine a form with several fields: 
>>> — From version, 
>>> — To Version 
>>> — Category (if not empty generate the report only for that category)
>>> — Target (user, admin, dev). (if not empty only generate the report for 
>>> that target audience)
>>> — + a “Generate” button to generate a dynamic "News and Networthy” report
>>> - We would also use Tags for each news to categorize it further, e.g. 
>>> “usability”, 

Re: [xwiki-devs] [Proposal] Release Notes Application

[Vincent Massol]

Hi again,

Done more coding (in front of the TV watching the Tennis David cup : France vs 
Croatia ;))...

I’ve now completely rewritten the 8.3M1 release notes using the release notes 
app:
https://www.evernote.com/l/AHc8Tp-XK6VMkY8ZL0YnNuEg7XLUavZliKM

FTR changes I’ve brought:
* In the end, "When the target audience is “developer” the screenshot is 
replaced by an example.” was not a good idea and I’ve dropped it.
* For the developers section, I’ve used a single column view. FTR here’s the 
wiki syntax for the New and Networthy part:

"
= New and Noteworthy (since XWiki 8.2) =

[[Full list of issues fixed and Dashboard for 
8.3>>http://jira.xwiki.org/secure/Dashboard.jspa?selectPageId=13629]].

== For Users ==

{{news columns="3" audience="user"/}}

== For Admins ==

{{news columns="3" audience="administrator"/}}

== For Developers ==

{{news columns="1" audience="developer"/}}
“

I’m quite happy about the result. Do you like it too?

Next step: Provide a UI for adding a release notes news (right now I’ve used 
the object editor to write the RN for 8.3M1).

Thanks
-Vincent


> On 17 Sep 2016, at 12:27, Vincent Massol  wrote:
> 
> I’ve done a quick POC locally, if you’re curious:
> 
> * 3 columns view (using {{news columns=“3”/}}:
> https://www.evernote.com/l/AHcrwTDtWzBL7JaGLsTvj3NcP95dEYwraOc
> 
> * 2 columns view (using {{news columns=“2"/}}:
> https://www.evernote.com/l/AHche7VWkv1KgLZPkWqbVv_ZGn728y-tAzw
> 
> * Livetable view of data:
> https://www.evernote.com/l/AHcItOb57M9AMIaU6HXBTO04c3o91dVKck4
> 
> Note1: I’ve added a title xproperty too.
> Note2: I’ve tweaked a bit the CSS of the galley macro but I could commit this 
> (see 
> http://extensions.xwiki.org/xwiki/bin/view/Extension/Gallery+Macro?viewer=comments#xwikicomment_6).
>  I’ll also need to talk to marius about the 128px padding for left/right 
> arrows (which I’ve reduced to 45px for the screenshots above). 
> 
> Thanks
> -Vincent
> 
>> On 16 Sep 2016, at 18:18, Vincent Massol  wrote:
>> 
>> Hi devs,
>> 
>> I’m planning to write a Release Notes Application for xwiki.org. I’d like to 
>> do something relatively simple in order to have a first working version.
>> 
>> Rationale
>> 
>> 
>> * Have nicer looking release notes by defining a structure and a common L
>> * For users, be able to see all the release notes item from a given version 
>> to another version and by category
>> 
>> Idea
>> 
>> 
>> Specifically for the “New and Networthy" section have:
>> - A visual that looks like this: https://www.jetbrains.com/datagrip/features/
>> - 2 columns layout
>> - For each item a screenshot and a summary text
>> - (optional) Have a “Learn more” button that goes to the item and provides 
>> more info (and possibly more screenshots if need be)
>> 
>> XProperties:
>> - Version (in which the item has been added). Static list
>> - Category (Help, Color Themes, Solr Search, AWM, etc). Static list
>> - Main screenshot 
>> - Summary text
>> - Additional content
>> - Target audience (User, Admin, Developer). Static list
>> 
>> Notes:
>> - If no “main screenshot” is provided then the generated report will put the 
>> item in a Miscellaneous section
>> 
>> For now I don’t want to handle other metadata for the releases notes, i.e. 
>> translations, upgrades, backward compat, tested browsers, etc). Precisely, 
>> I’m planning to write a “New and Networthy” application ATM, not a full 
>> “Release notes app”.
>> 
>> The way it could be used is through a {{news/}} macro, e.g.: {{news 
>> from=“6.4” to=“8.2” [categories=“help,awm,...”] 
>> [targetAudience=“user,admin”] /}}.
>> 
>> Usage
>> ==
>> 
>> - There would be a page in the wiki to see the livetable corresponding to 
>> all the release notes news (the xproperties above)
>> - Above this Livetable I imagine a form with several fields: 
>> — From version, 
>> — To Version 
>> — Category (if not empty generate the report only for that category)
>> — Target (user, admin, dev). (if not empty only generate the report for that 
>> target audience)
>> — + a “Generate” button to generate a dynamic "News and Networthy” report
>> - We would also use Tags for each news to categorize it further, e.g. 
>> “usability”, “performance”, and the LT would display the tag cloud. This 
>> will allow for example to see all items between such version and such 
>> version that are related to, say, performance
>> - We would still write a Release Notes page for each version but on that 
>> page, we would use the {{news/}} macro (with from = to = the version 
>> corresponding to that RN). On that page we would add all the other parts 
>> that are not in the app yet, i.e. translations, upgrades, backward compat, 
>> etc
>> - When an XWiki developers codes a new feature or improvement or new API 
>> will use the app to add it.
>> 
>> Future
>> ==
>> 
>> * Add a different release notes app to include the other metadata
>> * We could almost imagine using this “New and 

Re: [xwiki-devs] [Proposal] Release Notes Application

[Vincent Massol]

I’ve done a quick POC locally, if you’re curious:

* 3 columns view (using {{news columns=“3”/}}:
https://www.evernote.com/l/AHcrwTDtWzBL7JaGLsTvj3NcP95dEYwraOc

* 2 columns view (using {{news columns=“2"/}}:
https://www.evernote.com/l/AHche7VWkv1KgLZPkWqbVv_ZGn728y-tAzw

* Livetable view of data:
https://www.evernote.com/l/AHcItOb57M9AMIaU6HXBTO04c3o91dVKck4

Note1: I’ve added a title xproperty too.
Note2: I’ve tweaked a bit the CSS of the galley macro but I could commit this 
(see 
http://extensions.xwiki.org/xwiki/bin/view/Extension/Gallery+Macro?viewer=comments#xwikicomment_6).
 I’ll also need to talk to marius about the 128px padding for left/right arrows 
(which I’ve reduced to 45px for the screenshots above). 

Thanks
-Vincent

> On 16 Sep 2016, at 18:18, Vincent Massol  wrote:
> 
> Hi devs,
> 
> I’m planning to write a Release Notes Application for xwiki.org. I’d like to 
> do something relatively simple in order to have a first working version.
> 
> Rationale
> 
> 
> * Have nicer looking release notes by defining a structure and a common L
> * For users, be able to see all the release notes item from a given version 
> to another version and by category
> 
> Idea
> 
> 
> Specifically for the “New and Networthy" section have:
> - A visual that looks like this: https://www.jetbrains.com/datagrip/features/
> - 2 columns layout
> - For each item a screenshot and a summary text
> - (optional) Have a “Learn more” button that goes to the item and provides 
> more info (and possibly more screenshots if need be)
> 
> XProperties:
> - Version (in which the item has been added). Static list
> - Category (Help, Color Themes, Solr Search, AWM, etc). Static list
> - Main screenshot 
> - Summary text
> - Additional content
> - Target audience (User, Admin, Developer). Static list
> 
> Notes:
> - If no “main screenshot” is provided then the generated report will put the 
> item in a Miscellaneous section
> 
> For now I don’t want to handle other metadata for the releases notes, i.e. 
> translations, upgrades, backward compat, tested browsers, etc). Precisely, 
> I’m planning to write a “New and Networthy” application ATM, not a full 
> “Release notes app”.
> 
> The way it could be used is through a {{news/}} macro, e.g.: {{news 
> from=“6.4” to=“8.2” [categories=“help,awm,...”] [targetAudience=“user,admin”] 
> /}}.
> 
> Usage
> ==
> 
> - There would be a page in the wiki to see the livetable corresponding to all 
> the release notes news (the xproperties above)
> - Above this Livetable I imagine a form with several fields: 
> — From version, 
> — To Version 
> — Category (if not empty generate the report only for that category)
> — Target (user, admin, dev). (if not empty only generate the report for that 
> target audience)
> — + a “Generate” button to generate a dynamic "News and Networthy” report
> - We would also use Tags for each news to categorize it further, e.g. 
> “usability”, “performance”, and the LT would display the tag cloud. This will 
> allow for example to see all items between such version and such version that 
> are related to, say, performance
> - We would still write a Release Notes page for each version but on that 
> page, we would use the {{news/}} macro (with from = to = the version 
> corresponding to that RN). On that page we would add all the other parts that 
> are not in the app yet, i.e. translations, upgrades, backward compat, etc
> - When an XWiki developers codes a new feature or improvement or new API will 
> use the app to add it.
> 
> Future
> ==
> 
> * Add a different release notes app to include the other metadata
> * We could almost imagine using this “New and networthy” app to provide 
> reference documentation for our features… :) (along with automatic “since”). 
> That’s probably too science-fiction and I’m sure there are lots of gotchas 
> but just mentioning it here to make us dream a bit...
> 
> I’m starting to work on the POC. Let me know what you think.
> 
> Thanks
> -Vincent
___
devs mailing list
devs@xwiki.org
http://lists.xwiki.org/mailman/listinfo/devs

Re: [xwiki-devs] [Proposal] Release Notes Application

[Vincent Massol]

Forgot to mention one thing:
* When the target audience is “developer” the screenshot is replaced by an 
example.

Thanks
-Vincent

> On 16 Sep 2016, at 18:18, Vincent Massol  wrote:
> 
> Hi devs,
> 
> I’m planning to write a Release Notes Application for xwiki.org. I’d like to 
> do something relatively simple in order to have a first working version.
> 
> Rationale
> 
> 
> * Have nicer looking release notes by defining a structure and a common L
> * For users, be able to see all the release notes item from a given version 
> to another version and by category
> 
> Idea
> 
> 
> Specifically for the “New and Networthy" section have:
> - A visual that looks like this: https://www.jetbrains.com/datagrip/features/
> - 2 columns layout
> - For each item a screenshot and a summary text
> - (optional) Have a “Learn more” button that goes to the item and provides 
> more info (and possibly more screenshots if need be)
> 
> XProperties:
> - Version (in which the item has been added). Static list
> - Category (Help, Color Themes, Solr Search, AWM, etc). Static list
> - Main screenshot 
> - Summary text
> - Additional content
> - Target audience (User, Admin, Developer). Static list
> 
> Notes:
> - If no “main screenshot” is provided then the generated report will put the 
> item in a Miscellaneous section
> 
> For now I don’t want to handle other metadata for the releases notes, i.e. 
> translations, upgrades, backward compat, tested browsers, etc). Precisely, 
> I’m planning to write a “New and Networthy” application ATM, not a full 
> “Release notes app”.
> 
> The way it could be used is through a {{news/}} macro, e.g.: {{news 
> from=“6.4” to=“8.2” [categories=“help,awm,...”] [targetAudience=“user,admin”] 
> /}}.
> 
> Usage
> ==
> 
> - There would be a page in the wiki to see the livetable corresponding to all 
> the release notes news (the xproperties above)
> - Above this Livetable I imagine a form with several fields: 
> — From version, 
> — To Version 
> — Category (if not empty generate the report only for that category)
> — Target (user, admin, dev). (if not empty only generate the report for that 
> target audience)
> — + a “Generate” button to generate a dynamic "News and Networthy” report
> - We would also use Tags for each news to categorize it further, e.g. 
> “usability”, “performance”, and the LT would display the tag cloud. This will 
> allow for example to see all items between such version and such version that 
> are related to, say, performance
> - We would still write a Release Notes page for each version but on that 
> page, we would use the {{news/}} macro (with from = to = the version 
> corresponding to that RN). On that page we would add all the other parts that 
> are not in the app yet, i.e. translations, upgrades, backward compat, etc
> - When an XWiki developers codes a new feature or improvement or new API will 
> use the app to add it.
> 
> Future
> ==
> 
> * Add a different release notes app to include the other metadata
> * We could almost imagine using this “New and networthy” app to provide 
> reference documentation for our features… :) (along with automatic “since”). 
> That’s probably too science-fiction and I’m sure there are lots of gotchas 
> but just mentioning it here to make us dream a bit...
> 
> I’m starting to work on the POC. Let me know what you think.
> 
> Thanks
> -Vincent

___
devs mailing list
devs@xwiki.org
http://lists.xwiki.org/mailman/listinfo/devs