Wiki source code of XWiki Contrib

Version 71.4 by Eduard Moraru on 2015/05/25 14:09
Show last authors
1 {{box cssClass="floatinginfobox" title="**Contents**"}}
2 {{toc/}}
3 {{/box}}
4
5 **XWiki Contrib** is a community dedicated to collaborative development of XWiki related projects and extensions in the spirit of wiki communities. These projects are not part of the official XWiki distributions and are not maintained by the XWiki development team.
6
7 = Contrib Project List =
8
9 The full list projects is available on the [[##xwiki-contrib## user on GitHub>>https://github.com/organizations/xwiki-contrib]].
10
11 |=Project Name|=What is it?
12 |[[Curriki>>http://www.curriki.org]]|Open Source Curriculum Sharing and Editing based on the XWiki Platform.
13 |[[XWiki Office>>extensions:Extension.XWiki Office]]|MS Office Integration.
14 |[[XWiki Eclipse>>extensions:Extension.XWiki Eclipse]]|Remote/offline browsing of XWiki data in a standalone application or as an Eclipse plugin.
15 |[[XCLAMS>>xclams:Main.WebHome]]|Asset Management System and Social Network software for the Education Community.
16
17 = Hosting tools =
18
19 The project hosting forge can provide contributors with some or all of the following tools :
20
21 * A **GitHub repository**, under http://github.com/xwiki-contrib
22 * A **JIRA project** for tracking bugs and feature requests, at http://jira.xwiki.org/ and under the "XWiki Contributed projects" category. Note that each project should have its own JIRA project (we used to have a single generic JIRA project with different ##components## but this was creating difficulties).
23 * A generic **maven groupId**: ##org.xwiki.contrib## (or ##org.xwiki.contrib.<module name>## if the project has several modules). That's until the project reaches a certain size and visibility, in which case it can have its own maven group id.
24 * **Project pages** on extensions.xwiki.org to describe and document the project. When the project reaches a certain visibility and size it can have its own wiki on xwiki.org.
25
26 = Contributing to an existing project =
27
28 If you're interested to contribute to an existing project on http://github.com/xwiki-contrib, please send an email to **##devs AT xwiki.org##** (after having [[subscribed>>dev:Community.MailingLists]]), introducing yourself and explaining what you wish to do. Make sure to create an account on GitHub and mention this id in the email so that we can give you access. Thanks for helping out! :)
29
30 = Why join XWiki Contrib =
31
32 You could very well develop your XWiki extension in your own GitHub organization and you wonder why put your project on XWiki Contrib. Some reasons:
33
34 * You join a Community, the XWiki open source community. We value a lot the community notion and we want to be more like the Apache Software Foundation (strong sense of community) rather than Source Forge (list of independent projects, little community). In particular, this is why we ask you to introduce yourself when requesting a project.
35 * This makes your extension visible to the XWiki community and thus other contributors may want to join you in participating to the development of your extension (contribute on code, discussions, promotion, etc).
36 * You get some tools setup for your project (GitHub repository, Issue tracker, Wiki pages)
37
38 = Requesting a project =
39
40 The contrib project is open for anyone with a project that request it. Simply send us an email at **##devs AT xwiki.org##** using "**[Contrib]**" at the beginning of your email's subject. Let us know the name and a short description of your project. If your project has already been made available for download on extensions.xwiki.org, please precise it and point us to its page (If it is not, then no need to hurry, you will make it available once it's ready). Finally, let us know which of the listed tools you need. For GitHub access, you will need to register a user on http://github.com and let us know about it (a best practice is to have a username composed of the first letter of your first name immediately followed by your last name, the whole with no capital letter, for example **jdoe** if your name is John Doe).
41
42 When picking the GitHub name please follow the existing conventions:
43
44 * ##application-<xxx>## for apps
45 * ##macro-<xxx>## for macros only (if you project provides a macro but also provides other wiki pages then it's considered an app)
46 * ##api-<xxx>## for APIs only (same as for macro, if it contains UI as well, then you should call it an app instead)
47 * ##displayer-<xxx>## for custom displayers
48
49 For the actual project name part (##<xxx>## of the git repository name) it is preferred to use a single word (e.g. ##application-forum##). However, sometimes that is not descriptive enough, so you can either use multiple words next to eachother (e.g. ##application-filemanager##) if that makes sense and looks natural enough or, if not, you should separate the words with a dash (e.g. ##displayer-multiselect-suggest##). Whatever you decide, please try to keep it as short and descriptive as possible.
50
51 //Hint//: If in doubt, have a look at [[existing repository names>>https://github.com/xwiki-contrib]] for inspiration.
52
53 = Requesting snapshot builds for your project =
54
55 XWiki.org has a [[continuous build>>http://dev.xwiki.org/xwiki/bin/view/Community/ContinuousBuild]] which builds maven projects each time they are modified on GitHub and put the resulting artifact in our [[snapshots repository>>http://maven.xwiki.org/snapshots/]]. This is useful when you want people using your project as a dependency to continuously benefit from the improvements.
56
57 Your can ask for your project to be added to the continuous build by sending a mail to the devs list:
58
59 * First you need to use the xwiki parent pom to have the correct distribution management information:(((
60 {{code language="xml"}}
61 <project>
62 ...
63 <parent>
64 <groupId>org.xwiki.commons</groupId>
65 <artifactId>xwiki-commons-pom</artifactId>
66 <version>See https://github.com/xwiki/xwiki-commons/blob/master/pom.xml</version>
67 </parent>
68 ...
69 </project>
70 {{/code}}
71 )))
72 * Send a [[vote>>http://dev.xwiki.org/xwiki/bin/view/Community/Committership#HVoting]] on the [email protected] mailing list to discuss the addition of your project in the continuous build(((
73 {{code language="none"}}
74 [VOTE] Add myproject to the continuous build
75
76 Hi XWikiers,
77
78 I'm working on myproject and since it's used as a
79 dependency by someotherproject it'd be convenient
80 if it was built continuously.
81
82 Here's my +1.
83
84 Thanks,
85 Me.
86 {{/code}}
87 )))
88
89 = Release the project =
90
91 XWiki.org allows you to release your project on its maven repository as long as you follow the following steps:
92
93 * Use org.xwiki.contrib as groupId in your maven module
94 * Request for an account on [[Nexus>>http://nexus.xwiki.org]] by sending a mail to the [[Developer's list>>dev:Community.MailingLists]] mentioning the username you'd wish to have (you could also mention which extension you're planning to release to provide contextual information).
95 * Once you've received your credentials put them in ~~/.m2/settings.xml(((
96 {{code language="xml"}}
97 <settings>
98 ...
99 <servers>
100 ...
101 <server>
102 <id>xwiki-staging</id>
103 <username>username</username>
104 <password>********</password>
105 </server>
106 ...
107 </servers>
108 ...
109 </settings>
110 {{/code}}
111 )))
112 * Put the following configuration in your project pom.xml(((
113 {{code language="xml"}}
114 <project>
115 ...
116 <scm>
117 <connection>scm:git:git://github.com/xwiki-contrib/{extensionrepository}.git</connection>
118 <developerConnection>scm:git:[email protected]:xwiki-contrib/{extensionrepository}.git</developerConnection>
119 <url>https://github.com/xwiki-contrib/{extensionrepository}</url>
120 </scm>
121 ...
122 <distributionManagement>
123 <repository>
124 <id>xwiki-staging</id>
125 <name>XWiki Staging Repository</name>
126 <url>http://nexus.xwiki.org/nexus/service/local/staging/deploy/maven2/</url>
127 </repository>
128 </distributionManagement>
129 ...
130 </project>
131 {{/code}}
132
133 Where ##{extensionrepository}## is the name of the repository in http://github.com/xwiki-contrib/.
134 )))
135 * Release the project with the maven release plugin(((
136 {{code language="none"}}
137 mvn org.apache.maven.plugins:maven-release-plugin:2.5:prepare
138 {{/code}}
139
140 {{info}}
141 In case you're wondering why we force using this Maven Release plugin version, it's because versions < 2.5 of this plugin have a bug when using Git 1.9+ which leads to not resolving properly SNAPSHOT versions when tagging.
142 {{/info}}
143
144 {{error}}
145 If you are releasing from ##Microsoft Windows## and inherit from standard ##XWiki Commons root pom## < 6.2 you might have issues performing the release (see http://jira.xwiki.org/browse/XCOMMONS-553 for details). The workaround is to skip the enforcer plugin:
146
147 {{code language="none"}}
148 mvn release:perform -Darguments="-Dxwiki.enforcer.skip=true"
149 {{/code}}
150 {{/error}}
151
152 {{warning}}
153 If the application has also tests and you want to release the modules, but not run the tests, you should:
154
155 {{code language="none"}}
156 mvn org.apache.maven.plugins:maven-release-plugin:2.5:prepare -Pintegration-tests -Darguments="-DskipTests" -DskipTests
157 {{/code}}
158
159 If you want to skip the enforcer plugin, use:
160
161 {{code language="none"}}
162 mvn org.apache.maven.plugins:maven-release-plugin:2.5:prepare -Pintegration-tests -Darguments="-DskipTests -Dxwiki.enforcer.skip=true" -DskipTests
163 {{/code}}
164
165 {{/warning}}
166 )))
167 * In the recent versions of xwiki, we started signing the produced artifacts ([[http:~~/~~/en.wikipedia.org/wiki/Digital_signature>>http://en.wikipedia.org/wiki/Digital_signature]]). This helps downloaders check that indeed the binary is what was initially put in there, and was not replaced by an intruder.(((
168 The signing maven plugin is configured in the toplevel pom ( {{code}}<groupId>org.xwiki.commons</groupId><artifactId>xwiki-commons</artifactId>{{/code}} ) so any module that's inheriting from that will have the gpg plugin configured by default. To find out, get the effective pom of your module ( {{code}}mvn help:effective-pom{{/code}} ) and check if the gpg maven plugin is there (maven-gpg-plugin).
169
170 If you're gonna try to release like that, it will probably fail since the gpg plugin expects you to have a gnupg key with a password. You now have 2 options:
171
172 * Overwrite the settings of the gpg plugin in your pom to disable signing:(((
173 {{code}}
174 <profiles>
175 <profile>
176 <id>release</id>
177 <build>
178 <plugins>
179 <plugin>
180 <groupId>org.apache.maven.plugins</groupId>
181 <artifactId>maven-gpg-plugin</artifactId>
182 <configuration>
183 <skip>true</skip>
184 </configuration>
185 </plugin>
186 </plugins>
187 </build>
188 </profile>
189 </profiles>
190 {{/code}}
191 )))
192 * Configure your setup to sign properly. To do that, you will have to:
193 ** generate a gpg key which will be stored in your home folder and will be used by maven. On linux you can do that using the default gpg command ({{code}}gpg --gen-key{{/code}}, read the man page if you want to know more about the options). On Windows you can use [[Gpg4win>>http://www.gpg4win.org/]], while on Mac you have the [[GPG Suite>>https://gpgtools.org/]]. If you don't know what to fill in for the options requested by the tool, keep the defaults.
194 ** Tell maven the passphrase of this key (the one you entered upon key generation), either in the command line when performing the release {{code}}mvn release:perform -Darguments=-Dgpg.passphrase=PASSWORD{{/code}} or set it in your maven settings.xml like this(((
195 {{code}}
196 ...
197 <profile>
198 <id>xwiki</id>
199 <properties>
200 <gpg.passphrase>PASSWORD</gpg.passphrase>
201 </properties>
202 ...
203 {{/code}}
204 )))
205 )))
206 * You're done now, you can go on releasing(((
207 {{code language="none"}}
208 mvn org.apache.maven.plugins:maven-release-plugin:2.5:perform
209 {{/code}}
210
211 {{info}}
212 In case you're wondering why we force using this Maven Release plugin version, it's because versions < 2.5 of this plugin have a bug when using Git 1.9+ which leads to not resolving properly SNAPSHOT versions when tagging.
213 {{/info}}
214
215 {{warning}}
216 If the application has also tests and you want to release the modules, but not run the tests, you should:
217
218 {{code language="none"}}
219 mvn org.apache.maven.plugins:maven-release-plugin:2.5:perform -Pintegration-tests -Darguments="-DskipTests -Pintegration-tests" -DskipTests
220 {{/code}}
221
222 {{/warning}}
223 )))
224 * Note that you'll need to push the changes done by the release plugin: {{code}}git push origin master{{/code}}
225 * Ask for someone (on the devs mailing list or on IRC) to validate your release from the staging repository on [[Nexus>>http://nexus.xwiki.org]] to make your extension available on maven.xwiki.org. Alternatively if you've been granted the permissions you can do this yourself by understanding [[Nexus Staging>>http://books.sonatype.com/nexus-book/reference/staging-repositories.html]]. To perform promotion do the following:
226 ** Select the repository to validate in the Staging Repositories list
227 ** Click the "Close" button to close it. Wait a few seconds since it's done asynchronously.
228 ** Make sure to test your extension from the closed staging repo first since a released repo cannot be removed!
229 ** Once you want to move your extension from the Staging Repository to the Public Repository click the "Release" button. Wait a few seconds since it's done asynchronously.
230 * After that your release will be available for download on maven.xwiki.org and anyone will be able to use it as a dependency for his own project
231 * If your project is using JIRA, release the version in JIRA and add a new version label for the next version.
232 * Update the documentation for your project (or create it if there's none) on the [[Extensions Wiki>>extensions:Main.WebHome]] and make sure to add release notes information. See the next section for more.
233
234 = Publishing on extensions.xwiki.org =
235
236 The first step is to [[release>>||anchor="HReleasetheproject"]] your extension in the XWiki Maven Remote Repository. Then go the [[Extension wiki home page>>extensions:Main.WebHome]] and click on the [[Import>>extensions:ExtensionCode.ImportExtension]] button located inside the Contribute box (you'll need to be logged in). Then fill in your extension id (the format is ##<maven groupId>:<maven artifactId>##), select the ##maven-xwiki## repository and press the import button.
237
238 If you have already created an extension page manually on extensions.xwiki.org, the import will locate it (provided you've filled the correct extension id in your extension page, you can edit it in Object mode to fill it if that's not the case) and will overwrite data that it finds in your extension's ##pom.xml## file, preserving the rest of the information you've manually entered (like the description).
239
240 = Implementing your Maven build =
241
242 {{info}}
243 You can find [[reference documentation for the XAR Plugin>>dev:Community.XARPlugin]].
244 {{/info}}
245
246 Here's an example of how your ##pom.xml## should look like (adapt to your need) if you're contributing an application (XAR):
247
248 {{code language="xml"}}
249 <?xml version="1.0" encoding="UTF-8"?>
250
251 <!--
252 *
253 * See the NOTICE file distributed with this work for additional
254 * information regarding copyright ownership.
255 *
256 * This is free software; you can redistribute it and/or modify it
257 * under the terms of the GNU Lesser General Public License as
258 * published by the Free Software Foundation; either version 2.1 of
259 * the License, or (at your option) any later version.
260 *
261 * This software is distributed in the hope that it will be useful,
262 * but WITHOUT ANY WARRANTY; without even the implied warranty of
263 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
264 * Lesser General Public License for more details.
265 *
266 * You should have received a copy of the GNU Lesser General Public
267 * License along with this software; if not, write to the Free
268 * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
269 * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
270 *
271 -->
272
273 <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
274 <modelVersion>4.0.0</modelVersion>
275 <parent>
276 <groupId>org.xwiki.commons</groupId>
277 <artifactId>xwiki-commons-pom</artifactId>
278 <version>4.5</version>
279 </parent>
280 <groupId>org.xwiki.contrib</groupId>
281 <artifactId>your-extension-id</artifactId>
282 <version>1.0-SNAPSHOT</version>
283 <name>Your extension's name</name>
284 <packaging>xar</packaging>
285 <description>Your extension's description</description>
286 <scm>
287 <connection>scm:git:git://github.com/xwiki-contrib/(your extension id).git</connection>
288 <developerConnection>scm:git:[email protected]:xwiki-contrib/(your extension id).git</developerConnection>
289 <url>https://github.com/xwiki-contrib/(your extension id)</url>
290 </scm>
291 <developers>
292 <developer>
293 <id>scm id of developer 1</id>
294 <name>Full Name of developer 1 as registered on xwiki.org, e.g. Vincent Massol</name>
295 </developer>
296 ...
297 <developer>
298 <id>scm id of developer N</id>
299 <name>Full Name of developer N as registered on xwiki.org, e.g. Vincent Massol</name>
300 </developer>
301 </developers>
302 <properties>
303 <!-- Don't run CLIRR here since there's no Java code. -->
304 <xwiki.clirr.skip>true</xwiki.clirr.skip>
305 <!-- The Extension name. If not defined, the <name> property is used -->
306 <xwiki.extension.name>Your extension's name</xwiki.extension.name>
307 <!-- The extension's category -->
308 <xwiki.extension.category>application</xwiki.extension.category>
309 </properties>
310 <build>
311 <!-- Needed to add support for the XAR packaging -->
312 <extensions>
313 <extension>
314 <groupId>org.xwiki.commons</groupId>
315 <artifactId>xwiki-commons-tool-xar-handlers</artifactId>
316 <version>${commons.version}</version>
317 </extension>
318 </extensions>
319 <plugins>
320 <!-- The XAR packaging uses the XAR plugin and thus we need to define what version to use -->
321 <plugin>
322 <groupId>org.xwiki.commons</groupId>
323 <artifactId>xwiki-commons-tool-xar-plugin</artifactId>
324 <version>${commons.version}</version>
325 </plugin>
326 </plugins>
327 </build>
328 <distributionManagement>
329 <repository>
330 <id>xwiki-staging</id>
331 <name>XWiki Staging Repository</name>
332 <url>http://nexus.xwiki.org/nexus/service/local/staging/deploy/maven2/</url>
333 </repository>
334 </distributionManagement>
335 </project>
336 {{/code}}
337
338 It's very important that you set the following information as they'll be used when you publish your extension on [[extensions.xwiki.org>>extensions:Main.WebHome]]:
339
340 * Extension id
341 * Name
342 * Description
343 * Developers
344 * {{info}}New{{/info}} Category (using ##<xwiki.extension.category>##). Valid values are [[listed here>>extensions:Extension.Repository Application#HCategories]].
345
346 You'll also need to set the SCM information since using the Maven Release plugin will require those to be set.
347
348 If you've modified the ##groupId## or ##artifactId## of the extension you need to tell it to the Extension Manager so that it can handle upgrades and understand it's the same extension being upgraded. For example if the extension previously had an extension id of ##tdelafosse:meeting-application## and you're now using another id, you need to add the following property to your ##pom.xml##:
349
350 {{code language="xml"}}
351 <properties>
352 ...
353 <!-- Old names of this module used for retro compatibility when resolving dependencies of old extensions -->
354 <xwiki.extension.features>tdelafosse:meeting-application</xwiki.extension.features>
355 ...
356 </properties>
357 {{/code}}
358
359 {{info}}
360 In addition you need to pay attention to the version of the dependencies you're going to use (for example the parent POM dependency to ##org.xwiki.commons:xwiki-commons-pom##). If you wish your extension to be used by the maximum number of XWiki users you need to use the oldest dependencies version for which you extension still works. This is because your extension will only be able to be installed in XWiki versions satisfying those dependencies you expressed.
361 {{/info}}
362
363 = Application Design =
364
365 This section provides suggested best practices for writing an application. It is there to ensure your application is nice and easy to use by XWiki users.
366
367 * Put all your pages in a space dedicated for your application. This makes your application nicely compartmented. Pick a short space name (e.g. ##UserDirectory##). Examples of space names:(((
368 {{image reference="spaces.png"/}}
369 )))
370 * Ensure that all technical pages of your application are marked as ##hidden## so that users don't see them by default. To do so, edit those pages and tick the ##hidden## checkbox(((
371 {{image reference="hidden.png"/}}
372 )))
373 * Make sure you add a User Interface Extension (UIX) for the Application Panel extension point. This registers your application into the Application Panel:(((
374 {{image reference="applications-panel.png"/}}
375
376 This is done by adding an object of type ##XWiki.UIExtensionClass## in a page in your application space. We recommend having a page named ##<your space>.ApplicationsPanelEntry## (e.g. ##Blog.ApplicationPanelEntry##). For example:
377 {{image reference="application-uix.png"/}}
378
379 In order to have a nice-looking UIX page, We also recommend to have the following content on that page (insert it in wiki edit mode):
380
381 {{code}}
382 {{include document="XWiki.UIExtensionSheet" /}}
383 {{/code}}
384 )))
385
386 = Documenting =
387
388 After you've published your extension in the XWiki Maven Remote Repository, import it on [[extensions.xwiki.org>>extensions:Main.WebHome]] (click on "Import" on that page, you'll need to be logged in after registering yourself). This creates an extension page. Verify that your extension is marked as "Installable with the Extension Manager". This makes it easy for users to install it from within their XWiki instances.
389
390 {{warning}}
391 If you've already created the page on [[extensions.xwiki.org>>extensions:Main.WebHome]] prior to importing the extension then make sure you've used the correct extension id on your extension page as otherwise the import will not be able to import your extension data on the right page and instead it'll create another page and you'll find yourself with 2 pages...
392 {{/warning}}
393
394 Verify the value of the fields filled automatically by the import, namely:
395
396 * The page name
397 * The description
398 * The authors
399
400 If they're wrong you'll need to publish a new version of your extension and re-import it.
401
402 Edit it and provide nice user-friendly documentation. We recommend the following elements to be present:
403
404 * Description of what the extension does and the features it has (briefly). Provides an overview screenshot if it makes sense.
405 * Usage: explains how to use it
406 * Document each feature with some text but very importantly with a screenshot
407 * Fill the Compatibility section with the minimal version of XWiki your extension requires or has been tested with
408
409 Make sure to follow the [[Documentation guide>>dev:Community.DocGuide]]. For example take a special care to follow the [[Image best practices>>dev:Community.DocGuide#HScreenshots2FImages]] (use the {{{{{image}}}}} macro and don't take large screenshots as mentioned).
410
411 Make sure that you add documentation for your extension as soon as it's published on [[extensions.xwiki.org>>extensions:Main.WebHome]]. Otherwise nobody is going to start using it and people will start wondering what it's about.
412
413 Generally speaking check out documentation of existing extensions and try to mimic what you see (don't hesitate to go beyond the quality of what you see; you want your extension to be the most used, right? :) Documentation goes a long way towards achieving this!).

About

About

Support

Platform

User Guide

Admin Guide

Developer Guide

Projects

XWiki

Extensions

Other

Contribute

Status

Practices

Under the Hood

Get Involved

Get Connected