Re: [xwiki-devs] Extensions documentation (was:[Proposal] New xwiki-extensions GitHub organization)

Hello, Regarding applications best practices, I noticed that in the list of best practices there's nothing related to documenting your extension, apart from the fact that you should publish it on e.x.o.

It's better now, but I think it happened frequently to have pages created in extensions repository with only the default information and a download link, it makes difficult understanding and using the extension. For example for xar, it could be helpful to have at least the list of space(s) created by the app (if any), without having to look into the xar, or to install it with EM. Also in EM you see the pages installed, but only in the logs. After it's installed and you come back, you have no way to list the pages that belong to a specific extension. For an app you could have an entry in app panel,

but for a macro for example, it makes it difficult to find the macro afterwards.

Obviously for anything proposing an API, the API should be described (at least a javadoc link, better some digest in extension page IMHO).

The problem with adding the documentation AFTER publishing the extension (for example, you need to deploy it in a rush, so you don't have time to write proper documentation), is that you risk that users come first when extension is published, see nothing, and never come back. So I really think to have this part of the release process of an extension (and not something added after the time).

That's also a problem for example with some Maven plugins (even some officially supported), that propose only very minimal information on their site, and count on source code access and forums to provide essential infos to users…

WDYT ?

BR, Jeremie ---------- Forwarded message ---------- From: vincent(a)massol.net Date: 2014-05-07 8:43 GMT+02:00 Subject: Re: [xwiki-devs] [Proposal] New xwiki-extensions GitHub organization To: XWiki Developers Hi Marius, Thanks for your reply with challenging questions ;) See below. On 7 May 2014 at 07:31:34, Marius Dumitru Florea ( mariusdumitru.florea@xwiki.com(mailto:mariusdumitru.florea@xwiki.com)) wrote: The xwiki-extensions organization is under the responsibility of the XWiki Dev Team so it’s the XWiki Dev Team who will release its extensions. Yes I agree about your points. We need to handle this. Now === The new xwiki-extensions organization strategy will work only if we get more committers. The idea is to get the contributors of those extensions as committers for those extensions and thus be the RM for those extensions. Said differently we need a defined RM per repo. Note that longer release cycles is not an issue if the extensions has not had any code committed for it. What’s important is to be able to get it in the hands of users when there are important bug fixes or new features. It seems logical to me that those who commit these bugs/features release them. It’s obvious that separated extensions would mean a lot more work *if* we wanted to always release them all. But this is not the case. They’ll be released when those working on them want to release them or under user pressure. What we need to decide is how we want to handle Roadmaps and Release notes. I think we should start defining roadmaps per extension on e.x.o (we already support RN on e.x.o using either the jira macro or manually). Generally speaking for each extension that we add to xwiki-extensions we need a person resonsible for it, who’ll be in charge of defining the roadmaps, release notes and do the releases (he/she can delegate but he/she will still be responsible until that responsibility is handed to someone else. I believe this will be one criteria for accepting an extension in xwiki-extensions. Future ====== When we have the notion of Flavors, I believe it will simplify things to organize releases per flavor (XE can be considered a flavor ATM BTW). When this time comes we could decide to have a RM per flavor with a Roadmap/Release notes per flavor. I have no idea how many flavors we would have but I can think of 3: - xwiki.org flavor (FAQ app, JIRA macro, IRCBot app, etc) - knowledge base flavor (…) - collaborative apps flavor (calendar, meeting manager, file manager, etc) They’ll be chosen on a case by case basis with a VOTE for each. The person proposing it will put forward a maintainer for the extensions (who will be responsible of Roadmap/Releases Notes and performing releases). Note that IMO there are some conditions that we could define as base conditions: * Having had several releases already * Obeying the app best practices as defined by http://dev.xwiki.org/xwiki/bin/view/Community/ApplicationDevelopmentBestPra… * Having some tests and for apps, having at least one functional test (this means the functional test fwk is in place and ready to receive more tests) * Code style needs to obey http://dev.xwiki.org/xwiki/bin/view/Community/CodeStyle and generally speaking obey the practices defined on http://dev.xwiki.org Yes, same as what happens currently in the xwiki organization. The real goal of this proposal is to start having nice applications that can be a showcase of XWiki. Till now we have the engine and some extensions but none of them are developed as strongly as platform and they fall short. This is an effort to make a usable XWiki *product* vs just an XWiki *platform*. Again, we should take in only extensions that we can maintain, i.e. for which we have a volunteer to maintain them. TBH I don’t know if this will succeed or not but I feel it’s worth trying :) Do you have some better idea? Thanks -Vincent Github: xwiki and xwiki-contribs. “xwiki-contrib” organization in the way they want (some extensions there are not maintained, others are maintained) following changes: separate them from less maintained extensions. For example the top apps listed here: http://design.xwiki.org/xwiki/bin/view/Proposal/CollaborativeApplications xwiki-platform but not released with XE so that they can have a different release cycle (examples: FAQ app, IRCBot extension, JIRA macro, etc). Having different release cycle allow to release new versions quicker to our users (bug fixes, new features). be maintained by the XWiki Dev Team (aka XWiki Committers) bundled by default in XE. This rule will be reviewed and modified when we introduce the flavors concept in the future. The idea is that xwiki-platform will contain “core extensions” only and as we progress towards extensions, the number of core extensions will get smaller and smaller till possibly only the EM and what it requires. Everything else would be located in the xwiki-extensions organization organization so that each extension can be released independently of each other Roadmaps and aggregated Release Notes per Flavor (this is what we’re doing now with the “XE” flavor BTW). the xwiki-extensions organization without having them voted for the xwiki organization (although, over time, they would be able to become xwiki committers for the xwiki orgnization should they wish and if they’re voted in) Development Team” as author, which means they will be officially supported by the xwiki committers. > > > > > > WDYT? > > > > Thanks > > -Vincent & Thomas