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


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 <vinc...@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/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/data
>> grip/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
>>> _______________________________________________
>>> devs mailing list
>>> devs@xwiki.org
>>> http://lists.xwiki.org/mailman/listinfo/devs
devs mailing list

Reply via email to