[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: [email protected] <[email protected]> Date: 2014-05-07 8:43 GMT+02:00 Subject: Re: [xwiki-devs] [Proposal] New xwiki-extensions GitHub organization To: XWiki Developers <[email protected]> Hi Marius, Thanks for your reply with challenging questions ;) See below. On 7 May 2014 at 07:31:34, Marius Dumitru Florea ( [email protected](mailto:[email protected])) wrote:
You mentioned 2 needs and your proposal satisfies only the second. What about the first need?
Who's going to be responsible for releasing these extensions?
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.
We don't have many options when it comes to choosing a release manager for XE so I doubt committers will jump in to release these extensions unless they really need them. So we may end up with either
* having long release cycles for these extensions (which is against the second need you mentioned) because everyone has other things to do (note that this currently happens with some of the maintained extensions from xwiki-contrib), or * using the XE release manager and releasing all of them at once, but then having a separate GitHub repo for each extension is not justified.
In any case, the time spend on doing releases and the paper work around them will increase and it will most probably be the time of the XE release manager.
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)
As for moving extensions out of xwiki-contrib to xwiki-extensions, it's not simple. First, it's not very clear which contrib extensions will be chosen. You said "some maintained apps" but the link you gave is more about the functionality they provide and whether they fit in our view of the collaborative app suite. Then in order to move an extension you need to ask the contributors, otherwise you'll have to fork the repo and create a new extension id.
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/ApplicationDevelopmentBestPrac... * 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
Then what happens if an extension from xwiki-extensions stops being maintained, do we move it back to xwiki-contrib?
Yes, same as what happens currently in the xwiki organization.
I'm not fully convinced by your proposal.
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
Thanks, Marius
On Mon, May 5, 2014 at 5:43 PM, [email protected] wrote:
Hi devs,
Right now we have 2 organizations related to the XWiki project on Github: xwiki and xwiki-contribs.
The separation is currently the following: * XWiki Committers maintain the code in the “xwiki” organization * non XWiki Committers (aka contributors) maintain the code in the “xwiki-contrib” organization in the way they want (some extensions there are not maintained, others are maintained)
After brainstorming with Thomas Mortagne we’d like to propose the following changes:
Need =====
* Be able to extract some maintained apps from xwiki-contrib to separate them from less maintained extensions. For example the top apps listed here: http://design.xwiki.org/xwiki/bin/view/Proposal/CollaborativeApplications * Be able to extract some extensions currently located in 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).
Proposal =======
* Introduce a new xwiki-extensions organization in GitHub which would be maintained by the XWiki Dev Team (aka XWiki Committers)
* For now, move out of xwiki/xwiki-platform all modules that are not 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
* Have one repository per extensions in the xwiki-extensions github organization so that each extension can be released independently of each other
* In order to make it simple to release, the idea would be to have Roadmaps and aggregated Release Notes per Flavor (this is what we’re doing now with the “XE” flavor BTW).
* We will be able to vote in committers for specific repos located in 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)
* Extensions from xwiki-extensions published on e.x.o would have “XWiki Development Team” as author, which means they will be officially supported by the xwiki committers.
WDYT?
Thanks -Vincent & Thomas
devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
On 7 May 2014 at 15:58:39, Jeremie BOUSQUET ([email protected](mailto:[email protected])) wrote:
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.
Actually this is documented here for contrib: http://contrib.xwiki.org/xwiki/bin/view/Main/WebHome#HDocumenting But it’s minimal and it’s not for the “xwiki” organization indeed…
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,
Yes and it’s a defined best practice already. Future: apps will probably have their app descriptor listing all the pages making the app
but for a macro for example, it makes it difficult to find the macro afterwards.
This can be solved by having an admin UI to list all macros available in the wiki. We have XWiki.WikiMacros but 1) there’s no navigation to it and 2) it only lists wiki macros. I agree that we need this.
Obviously for anything proposing an API, the API should be described (at least a javadoc link, better some digest in extension page IMHO).
Regarding javadoc, we had the idea of adding this as field in the Extension Class. I was sure we had a jira issue but I cannot find it ATM.
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).
Note that this is already the case and is covered by the 2 “documentation” fields in JIRA :) It could be added on contrib.xwiki.org’s home page too.
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…
BTW on this, we have http://dev.xwiki.org/xwiki/bin/view/Community/Contributing#HStrategiesforans...
WDYT ?
Sure, you can reply with ideas here and we can brainstorm. Are you willing to help set something up? There are already a few suggestions above that can acted on. Thanks -Vincent
BR, Jeremie
---------- Forwarded message ---------- From: [email protected] 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 ( [email protected](mailto:[email protected])) wrote:
You mentioned 2 needs and your proposal satisfies only the second. What about the first need?
Who's going to be responsible for releasing these extensions?
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.
We don't have many options when it comes to choosing a release manager for XE so I doubt committers will jump in to release these extensions unless they really need them. So we may end up with either
* having long release cycles for these extensions (which is against the second need you mentioned) because everyone has other things to do (note that this currently happens with some of the maintained extensions from xwiki-contrib), or * using the XE release manager and releasing all of them at once, but then having a separate GitHub repo for each extension is not justified.
In any case, the time spend on doing releases and the paper work around them will increase and it will most probably be the time of the XE release manager.
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)
As for moving extensions out of xwiki-contrib to xwiki-extensions, it's not simple. First, it's not very clear which contrib extensions will be chosen. You said "some maintained apps" but the link you gave is more about the functionality they provide and whether they fit in our view of the collaborative app suite. Then in order to move an extension you need to ask the contributors, otherwise you'll have to fork the repo and create a new extension id.
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/ApplicationDevelopmentBestPrac... * 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
Then what happens if an extension from xwiki-extensions stops being maintained, do we move it back to xwiki-contrib?
Yes, same as what happens currently in the xwiki organization.
I'm not fully convinced by your proposal.
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
Thanks, Marius
On Mon, May 5, 2014 at 5:43 PM, [email protected] wrote:
Hi devs,
Right now we have 2 organizations related to the XWiki project on Github: xwiki and xwiki-contribs.
The separation is currently the following: * XWiki Committers maintain the code in the “xwiki” organization * non XWiki Committers (aka contributors) maintain the code in the “xwiki-contrib” organization in the way they want (some extensions there are not maintained, others are maintained)
After brainstorming with Thomas Mortagne we’d like to propose the following changes:
Need =====
* Be able to extract some maintained apps from xwiki-contrib to separate them from less maintained extensions. For example the top apps listed here: http://design.xwiki.org/xwiki/bin/view/Proposal/CollaborativeApplications * Be able to extract some extensions currently located in 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).
Proposal =======
* Introduce a new xwiki-extensions organization in GitHub which would be maintained by the XWiki Dev Team (aka XWiki Committers)
* For now, move out of xwiki/xwiki-platform all modules that are not 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
* Have one repository per extensions in the xwiki-extensions github organization so that each extension can be released independently of each other
* In order to make it simple to release, the idea would be to have Roadmaps and aggregated Release Notes per Flavor (this is what we’re doing now with the “XE” flavor BTW).
* We will be able to vote in committers for specific repos located in 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)
* Extensions from xwiki-extensions published on e.x.o would have “XWiki Development Team” as author, which means they will be officially supported by the xwiki committers.
WDYT?
Thanks -Vincent & Thomas
participants (2)
-
Jeremie BOUSQUET -
vincent＠massol.net