Wiki source code of XWiki Contrib
Version 35.2 by Vincent Massol on 2013/06/05 20:51
Show last authors
author | version | line-number | content |
---|---|---|---|
1 | {{box cssClass="floatinginfobox" title="**Contents**"}} | ||
2 | {{toc/}} | ||
3 | {{/box}} | ||
4 | |||
5 | The **XWiki Contrib Project** provides hosting for projects related to XWiki. 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 | |||
16 | = Hosting tools = | ||
17 | |||
18 | The project hosting forge can provide contributors with some or all of the following tools : | ||
19 | |||
20 | * A **GitHub repository**, under http://github.com/xwiki-contrib | ||
21 | * A **JIRA project** for tracking bugs and feature requests, at http://jira.xwiki.org/ and under the "XWiki Contributed projects" category. Note that there will be a generic JIRA project to be used by all projects till they achieve a first release or till they grow to a size significant enough to warrant a dedicated JIRA project | ||
22 | * A generic **maven groupId**: ##org.xwiki.contrib.<module name>## (until the project reaches a certain size and visibility, in which case it can have its own maven group id). For example: ##org.xwiki.contrib.mailarchive##. | ||
23 | * **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. | ||
24 | |||
25 | = Requesting a project = | ||
26 | |||
27 | 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). | ||
28 | |||
29 | = Requesting snapshost builds for your project = | ||
30 | |||
31 | 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. | ||
32 | |||
33 | Your can ask for your project to be added to the continuous build: | ||
34 | |||
35 | * First you need to use the xwiki parent pom to have the correct distribution management information:((( | ||
36 | {{code language="xml"}} | ||
37 | <project> | ||
38 | ... | ||
39 | <parent> | ||
40 | <groupId>org.xwiki.commons</groupId> | ||
41 | <artifactId>xwiki-commons-pom</artifactId> | ||
42 | <version>See https://github.com/xwiki/xwiki-commons/blob/master/pom.xml</version> | ||
43 | </parent> | ||
44 | ... | ||
45 | </project> | ||
46 | {{/code}} | ||
47 | ))) | ||
48 | * 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((( | ||
49 | {{code language="none"}} | ||
50 | [VOTE] Add myproject to the continuous build | ||
51 | |||
52 | Hi XWikiers, | ||
53 | |||
54 | I'm working on myproject and since it's used as a | ||
55 | dependency by someotherproject it'd be convenient | ||
56 | if it was built continuously. | ||
57 | |||
58 | Here's my +1. | ||
59 | |||
60 | Thanks, | ||
61 | Me. | ||
62 | {{/code}} | ||
63 | ))) | ||
64 | |||
65 | = Release the project = | ||
66 | |||
67 | XWiki.org allows you to release your project on its maven repository as long as you follow the following steps: | ||
68 | |||
69 | * Use org.xwiki.contrib as groupId in your maven module | ||
70 | * Request for an account on http://nexus.xwiki.org on [email protected] | ||
71 | * Once you've received your credentials put them in ~~/.m2/settings.xml((( | ||
72 | {{code language="xml"}} | ||
73 | <settings> | ||
74 | ... | ||
75 | <servers> | ||
76 | ... | ||
77 | <server> | ||
78 | <id>xwiki-staging</id> | ||
79 | <username>username</username> | ||
80 | <password>********</password> | ||
81 | </server> | ||
82 | ... | ||
83 | </servers> | ||
84 | ... | ||
85 | </settings> | ||
86 | {{/code}} | ||
87 | ))) | ||
88 | * Put the following configuration in your project pom.xml((( | ||
89 | {{code language="xml"}} | ||
90 | <project> | ||
91 | ... | ||
92 | <scm> | ||
93 | <connection>scm:git:git://github.com/xwiki-contrib/{extensionrepository}.git</connection> | ||
94 | <developerConnection>scm:git:[email protected]:xwiki-contrib/{extensionrepository}.git</developerConnection> | ||
95 | <url>https://github.com/xwiki-contrib/{extensionrepository}</url> | ||
96 | </scm> | ||
97 | ... | ||
98 | <distributionManagement> | ||
99 | <repository> | ||
100 | <id>xwiki-staging</id> | ||
101 | <name>XWiki Staging Repository</name> | ||
102 | <url>http://nexus.xwiki.org/nexus/service/local/staging/deploy/maven2/</url> | ||
103 | </repository> | ||
104 | </distributionManagement> | ||
105 | ... | ||
106 | </project> | ||
107 | {{/code}} | ||
108 | |||
109 | Where ##{extensionrepository}## is the name of the repository in [[http://github.com/xwiki-contrib/>>http://github.com/xwiki-contrib/]]. | ||
110 | ))) | ||
111 | * Release the project with the maven release plugin((( | ||
112 | {{code language="none"}} | ||
113 | mvn release:prepare | ||
114 | {{/code}} | ||
115 | ))) | ||
116 | |||
117 | (((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. | ||
118 | |||
119 | 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). | ||
120 | |||
121 | 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: | ||
122 | |||
123 | * Overwrite the settings of the gpg plugin in your pom to disable signing | ||
124 | * Configure your setup to sign properly. To do that, you will have to: | ||
125 | ** 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 win and/or mac, you can use tools like [[GNUPG>>http://www.coresecure.com/v5/gnupg.html]] or [[GPGTools>>http://www.gpgtools.org/installer/index.html]]. If you don't know what to fill in for the options requested by the tool, keep the defaults. | ||
126 | ** 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((( | ||
127 | {{code}} | ||
128 | ... | ||
129 | <profile> | ||
130 | <id>xwiki</id> | ||
131 | <properties> | ||
132 | <gpg.passphrase>PASSWORD</gpg.passphrase> | ||
133 | </properties> | ||
134 | ... | ||
135 | {{/code}} | ||
136 | ))) | ||
137 | ))) | ||
138 | |||
139 | You're done now, you can go on releasing. | ||
140 | |||
141 | {{code language="none"}} | ||
142 | mvn release:perform | ||
143 | {{/code}} | ||
144 | * Note that you'll need to push the changes done by the release plugin: {{code}}git push origin master{{/code}} | ||
145 | * Ask for someone to promote your release (ie. make it available on maven.xwiki.org) in the thread you've created earlier | ||
146 | * 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 | ||
147 | |||
148 | = Publishing on extensions.xwiki.org = | ||
149 | |||
150 | 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. | ||
151 | |||
152 | 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). | ||
153 | |||
154 | = Implementing your Maven build = | ||
155 | |||
156 | Here's an example of how your ##pom.xml## should look like (adapt to your need) if you're contributing an application (XAR): | ||
157 | |||
158 | {{code language="xml"}} | ||
159 | <?xml version="1.0" encoding="UTF-8"?> | ||
160 | |||
161 | <!-- | ||
162 | * | ||
163 | * See the NOTICE file distributed with this work for additional | ||
164 | * information regarding copyright ownership. | ||
165 | * | ||
166 | * This is free software; you can redistribute it and/or modify it | ||
167 | * under the terms of the GNU Lesser General Public License as | ||
168 | * published by the Free Software Foundation; either version 2.1 of | ||
169 | * the License, or (at your option) any later version. | ||
170 | * | ||
171 | * This software is distributed in the hope that it will be useful, | ||
172 | * but WITHOUT ANY WARRANTY; without even the implied warranty of | ||
173 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | ||
174 | * Lesser General Public License for more details. | ||
175 | * | ||
176 | * You should have received a copy of the GNU Lesser General Public | ||
177 | * License along with this software; if not, write to the Free | ||
178 | * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA | ||
179 | * 02110-1301 USA, or see the FSF site: http://www.fsf.org. | ||
180 | * | ||
181 | --> | ||
182 | |||
183 | <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"> | ||
184 | <modelVersion>4.0.0</modelVersion> | ||
185 | <parent> | ||
186 | <groupId>org.xwiki.commons</groupId> | ||
187 | <artifactId>xwiki-commons-pom</artifactId> | ||
188 | <version>4.5</version> | ||
189 | </parent> | ||
190 | <groupId>org.xwiki.contrib</groupId> | ||
191 | <artifactId>your-extension-id</artifactId> | ||
192 | <version>1.0-SNAPSHOT</version> | ||
193 | <name>Your extension's name</name> | ||
194 | <packaging>xar</packaging> | ||
195 | <description>Your extension's description</description> | ||
196 | <scm> | ||
197 | <connection>scm:git:git://github.com/xwiki-contrib/(your extension id).git</connection> | ||
198 | <developerConnection>scm:git:[email protected]:xwiki-contrib/(your extension id).git</developerConnection> | ||
199 | <url>https://github.com/xwiki-contrib/(your extension id)</url> | ||
200 | </scm> | ||
201 | <developers> | ||
202 | <developer> | ||
203 | <id>id of developer 1</id> | ||
204 | <name>Full Name of developer 1 as registered on xwiki.org, e.g. Vincent Massol</name> | ||
205 | </developer> | ||
206 | ... | ||
207 | <developer> | ||
208 | <id>id of developer N</id> | ||
209 | <name>Full Name of developer N as registered on xwiki.org, e.g. Vincent Massol</name> | ||
210 | </developer> | ||
211 | </developers> | ||
212 | <properties> | ||
213 | <!-- Don't run CLIRR here since there's no Java code. --> | ||
214 | <xwiki.clirr.skip>true</xwiki.clirr.skip> | ||
215 | </properties> | ||
216 | <build> | ||
217 | <!-- Needed to add support for the XAR packaging --> | ||
218 | <extensions> | ||
219 | <extension> | ||
220 | <groupId>org.xwiki.commons</groupId> | ||
221 | <artifactId>xwiki-commons-tool-xar-handlers</artifactId> | ||
222 | <version>${commons.version}</version> | ||
223 | </extension> | ||
224 | </extensions> | ||
225 | <plugins> | ||
226 | <!-- The XAR packaging uses the XAR plugin and thus we need to define what version to use --> | ||
227 | <plugin> | ||
228 | <groupId>org.xwiki.commons</groupId> | ||
229 | <artifactId>xwiki-commons-tool-xar-plugin</artifactId> | ||
230 | <version>${commons.version}</version> | ||
231 | </plugin> | ||
232 | </plugins> | ||
233 | </build> | ||
234 | <distributionManagement> | ||
235 | <repository> | ||
236 | <id>xwiki-staging</id> | ||
237 | <name>XWiki Staging Repository</name> | ||
238 | <url>http://nexus.xwiki.org/nexus/service/local/staging/deploy/maven2/</url> | ||
239 | </repository> | ||
240 | </distributionManagement> | ||
241 | </project> | ||
242 | {{/code}} | ||
243 | |||
244 | 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]]: | ||
245 | * Extension id | ||
246 | * Name | ||
247 | * Description | ||
248 | * Developers | ||
249 | |||
250 | You'll also need to set the SCM information since using the Maven Release plugin will require those to be set. | ||
251 | |||
252 | = Application Design = | ||
253 | |||
254 | 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. | ||
255 | |||
256 | * 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:((( | ||
257 | {{image reference="spaces.png"/}} | ||
258 | ))) | ||
259 | * 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((( | ||
260 | {{image reference="hidden.png"/}} | ||
261 | ))) | ||
262 | * Make sure you add a User Interface Extension (UIX) for the Application Panel extension point. This registers your application into the Application Panel:((( | ||
263 | {{image reference="applications-panel.png"/}} | ||
264 | |||
265 | 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: | ||
266 | {{image reference="application-uix.png"/}} | ||
267 | |||
268 | 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): | ||
269 | |||
270 | {{code}} | ||
271 | {{include document="XWiki.UIExtensionSheet" /}} | ||
272 | {{/code}} | ||
273 | ))) |