On 17 Sep 2016, at 12:27, Vincent Massol <vincent(a)massol.net> 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=c…). 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 <vincent(a)massol.net> 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&F > * 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

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 France vs Croatia ;))... notes app: replaced by an example.” was not a good idea and I’ve dropped it. the wiki syntax for the New and Networthy part: http://jira.xwiki.org/secure/Dashboard.jspa?selectPageId=13629]]. used the object editor to write the RN for 8.3M1). 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). like to do something relatively simple in order to have a first working version. common L&F version to another version and by category datagrip/features/ provides more info (and possibly more screenshots if need be) put the item in a Miscellaneous section 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”. from=“6.4” to=“8.2” [categories=“help,awm,...”] [targetAudience=“user,admin”] /}}. to all the release notes news (the xproperties above) for that target audience) report “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 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 API will use the app to add it. 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... _______________________________________________ devs mailing list devs(a)xwiki.org http://lists.xwiki.org/mailman/listinfo/devs

On 19 Sep 2016, at 13:46, Marius Dumitru Florea <mariusdumitru.florea(a)xwiki.com> wrote: On Sat, Sep 17, 2016 at 6:29 PM, Vincent Massol <vincent(a)massol.net> wrote: 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 <vincent(a)massol.net> 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 <vincent(a)massol.net> 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&F >>> * 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

On Fri, Sep 16, 2016 at 7:18 PM, Vincent Massol <vincent(a)massol.net> wrote: 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. Thanks, Caty

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) < valicac(a)gmail.com&gt; wrote:

wrote: ExtensionVersionClass Because it’s very different! Actually there isn’t a single field that is the same as my ChangesClass :) 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 [snip] _______________________________________________ devs mailing list devs(a)xwiki.org http://lists.xwiki.org/mailman/listinfo/devs

On 19 Sep 2016, at 14:13, Ecaterina Moraru (Valica) &lt;valicac(a)gmail.com&gt; wrote:

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. Thanks, Caty > > I’m starting to work on the POC. Let me know what you think. > > Thanks > -Vincent