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

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

Reply via email to