Hide last authors
Thomas Mortagne 119.1 1 {{box cssClass="floatinginfobox" title="**Contents**"}}
2 {{toc/}}
Jerome 10.1 3 {{/box}}
Admin 1.1 4
Thomas Mortagne 119.1 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.
Admin 1.1 6
Thomas Mortagne 119.1 7 = Contrib Project List =
Jerome 2.1 8
Thomas Mortagne 119.1 9 The full list of Contrib projects is available [[on GitHub>>https://github.com/organizations/xwiki-contrib]].
Vincent Massol 14.1 10
Thomas Mortagne 119.1 11 Note that projects not having an active maintainer are moved to the [[Attic>>https://github.com/organizations/xwiki-attic]] (The definition of "active" is left to the community and anyone can propose to move inactive projects to the Attic).
Vincent Massol 103.1 12
Thomas Mortagne 119.1 13 = Hosting tools =
Vincent Massol 14.1 14
Thomas Mortagne 119.1 15 The project hosting forge can provide contributors with some or all of the following tools:
Jerome 10.1 16
Vincent Massol 126.3 17 * A **GitHub repository**, under https://github.com/xwiki-contrib
Thomas Mortagne 119.1 18 * A **JIRA project** for tracking bugs and feature requests, at https://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).
19 * 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.
20 * **Project pages** on [[extensions.xwiki.org>>extensions:Main.WebHome]] to describe and document the project. When the project reaches a certain visibility and size it can have its own wiki on xwiki.org.
Vincent Massol 126.3 21 * A **CI job** on https://ci.xwiki.org for building the project automatically on each commit (more specifically see [[XWiki Contrib jobs>>https://ci.xwiki.org/view/Contrib/job/XWiki%20Contrib/]]).
22 * A **Sonar project report** on https://sonar.xwiki.org to analyze the project's quality with various metrics.
23 * **Translations**, under the [[l10n platform>>https://l10n.xwiki.org]].
Vincent Massol 126.1 24 * There's no dedicated Forum. For the moment, all the projects share the [[Development category of the forum>>https://forum.xwiki.org/c/Dev]].
Vincent Massol 125.1 25 * There's no dedicated chat room, the [[main #xwiki chat room>>dev:Community.Chat]] must be used.
Jerome 2.1 26
Thomas Mortagne 119.1 27 = Contributing to an existing project =
Vincent Massol 42.1 28
Vincent Massol 126.3 29 If you're interested to contribute to an existing project on https://github.com/xwiki-contrib, please send a post to the [[Forum (dev category)>>https://forum.xwiki.org/c/Dev]], 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! :)
Vincent Massol 42.1 30
Thomas Mortagne 119.1 31 = Why join XWiki Contrib =
Vincent Massol 55.1 32
Thomas Mortagne 119.1 33 You could very well develop your XWiki extension in your own GitHub organization and you might wonder why put your project on XWiki Contrib. Some reasons:
Eduard Moraru 63.1 34
Thomas Mortagne 119.1 35 * 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.
36 * 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).
37 * You get some tools setup for your project (GitHub repository, Issue tracker, Wiki pages)
Vincent Massol 55.1 38
Vincent Massol 124.1 39 = Development Practices =
40
41 In order to simplify participating to any project in ##xwiki-contrib##, the recommended development practices to follow are [[all those found on dev.xwiki.org>>dev:Main.WebHome]](i.e. the same as for the ##xwiki## github organization). This prevents the issue that someone who wants to participate to more than 1 project needs to learn several dev practices; they're all the same. Now, these practices are best practices and the intent is that committers try to follow them as much as they can, in their capacity. Other committers reviewing code should be lenient in their comments and sentences like "You must do xxx" should be avoided and instead sentences like "When you have the time, it would be nice if you could...". OTOH, when a committer joins ##xwiki-contrib##, he/she should understand that these best practices exist (and possibly spend some time reading them), and agree about following them as much as he/she can. Obviously anyone is free to discuss an existing rule and propose changing it or dropping it altogether.
42
Thomas Mortagne 119.1 43 = Requesting a project =
44
Vincent Massol 126.3 45 The contrib project is open for anyone who wish to start a new project. Simply send a post on the [[Forum (dev category)>>https://forum.xwiki.org/c/Dev]] using the ##contrib## tag. Let us know the name and a short description of the project. If your project has already been made available for download on extensions.xwiki.org, please mention 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 tools listed above you need. For GitHub access, you will need to register a user on https://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).
Thomas Mortagne 119.1 46
47 == Choosing the name ==
48
49 When picking the GitHub name please follow the existing conventions:
50
51 * ##application-<xxx>## for apps
52 * ##macro-<xxx>## for macros only (if you project provides a macro but also provides other wiki pages then it's considered an app)
53 * ##api-<xxx>## for APIs only (same as for macro, if it contains UI as well, then you should call it an app instead)
54 * ##displayer-<xxx>## for custom displayers
55 * ##syntax-<xxx>## for rendering syntaxes
56 * ##authenticator-<xxx>## for authenticators
57 * ##skin-<xxx>## for skins
Oana-Lavinia Florean 131.1 58 * webjar-<xxx> for webjar packagings
Thomas Mortagne 119.1 59
60 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 each other (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.
61
62 Special cases:
63
64 * ##icon-themes##. This is a reserved name and it's also the name of a [[special repository containing all Icon Themes>>>https://github.com/xwiki-contrib/icon-themes]]. If you want to contribute a new Icon theme, you should add a new ##icon-theme-<yyy>## directory in this repository. We release all Icon Themes together with the same version as we consider them too small to be released separately.
65 * ##color-themes##. This is a reserved name and it's also the name of a [[special repository containing all Color Themes>>>https://github.com/xwiki-contrib/color-themes]]. If you want to contribute a new Color theme, you should add a new ##color-theme-<yyy>## directory in this repository. We release all Color Themes together with the same version as we consider them too small to be released separately.
66
67 //Hint//: When in doubt, have a look at [[existing repository names>>https://github.com/xwiki-contrib]] for inspiration.
68
69 Please try to avoid using the ##xwiki-## prefix since this one is used by XWiki GitHub organization repositories (i.e. Core modules).
70
71 == README.md Template ==
72
73 It's very useful for projects to have a ##README.md## file providing various information (who the lead is, the best practices for contributing to this project, etc). We recommend using the following template:
74
75 {{code language="none"}}
76 # <Pretty name of Extension, e.g. Flash Messages Application>
77
78 <Short Description of Extension, taken from the description element in the pom.xml>
79
80 * Project Lead: [<info taken from the jira project, e.g. Vincent Massol>](<url to user profile on xwiki.org)
81 <if single extension page>
Vincent Massol 126.3 82 * [Documentation & Download](<url on e.x.o, e.g. https://extensions.xwiki.org/xwiki/bin/view/Extension/Flash+messages+application>)
Thomas Mortagne 119.1 83 </if single extension page>
84 <if several extension pages>
85 * Documentation & Downloads:
86 * [<pretty name of page1, e.g. My App API](<url1 on e.x.o)
87 ...
88 * [<pretty name of pageN, e.g. My App API](<urlN on e.x.o)
89 </if several extension pages>
Vincent Massol 126.3 90 * [Issue Tracker](<url on jira.xwiki.org, e.g. https://jira.xwiki.org/browse/XAFLASHM>)
Oana-Lavinia Florean 131.1 91 * Communication: [Forum](<url, e.g. https://forum.xwiki.org></url>), [Chat](<url, e.g. https://dev.xwiki.org/xwiki/bin/view/Community/Chat>)
Thomas Mortagne 119.1 92 <if link pointing to all dev practices>
93 * [Development Practices](<URL pointing to a site defining the list of practices to be followed by contributors when contributing on this project>)
94 </if link pointing to all dev practices>
95 <if no single link pointing to all dev practices>
96 * Development Practices:
97 * <best practice 1, possibly with some link>
98 ...
99 * <best practice N, possibly with some link>
100 </if no single link pointing to all dev practices>
101 * Minimal XWiki version supported: <taken from the pom.xml, e.g. XWiki 6.4.7>
102 * License: <license,taken from the pom.xml, e.g. LGPL 2.1>.
103 <if translation is used>
104 * [Translations](<url on l10n to translations for this extension>)
105 </if translation is used>
106 <if translation is not used>
107 * Translations: N/A
108 </if translation is not used>
109 <if sonar is used>
Vincent Massol 126.3 110 * [Sonar Dashboard](<url to the project’s dashboard on sonar.xwiki.org, e.g. https://sonar.xwiki.org/dashboard/index/10464>)
Thomas Mortagne 119.1 111 </if sonar is used>
112 <if sonar is not used>
113 * Sonar Dashboard: N/A
114 </if sonar is not used>
115 <if ci is used>
Vincent Massol 126.3 116 * Continuous Integration Status: [![Build Status](https://ci.xwiki.org/job/XWiki%20Contrib/job/<job name on ci.xwiki.org>/job/master/badge/icon)](https://ci.xwiki.org/job/XWiki%20Contrib/job/<job name on ci.xwiki.org>/job/master/)
Thomas Mortagne 119.1 117 </if ci is used>
118 <if ci is not used>
119 * Continuous Integration Status: N/A
120 </if ci is not used>
121
122 <optional>
123 ## Whatever
124 ...
125 </optional>
126 {{/code}}
127
128 Here's [[an example>>https://github.com/xwiki-contrib/application-antispam/blob/master/README.md]].
129
130 {{info}}
Vincent Massol 126.3 131 In order to find the build status URL for the badges, you should navigate to your project on ci.xwiki.org and then click on the "Embeddable Build Status" link ([[example>>https://ci.xwiki.org/view/Contrib/job/XWiki%20Contrib/job/application-antispam/job/master/badge/]]). Use the "Markdown (with view)" and "unprotected" links.
Thomas Mortagne 119.1 132 {{/info}}
133
134 == For XWiki Admins ==
135
136 You have to create 2 things:
137
138 * A GitHub repository
139 * a JIRA project
140
141 === GitHub Repository Creation ===
142
143 When creating a new ##xwiki-contrib## repository on GitHub please make sure to:
144
Vincent Massol 128.2 145 * Uncheck the "wiki", "issues" and "projects" checkboxes in the settings
Vincent Massol 128.3 146 * Add the ##xwikiorg## group in the "Manage Access" settings. Make sure to select the "Write" permission (it's "Read" by default).
Vincent Massol 128.4 147 * Under "Notifications", add the notifications AT xwiki DOT org email
Thomas Mortagne 119.1 148 * Add a default ##.gitignore## file (or tell the project owner to add one), by copying the {{scm project="xwiki-commons" path=".gitignore"}}##.gitignore from ##xwiki-commons##{{/scm}}.
149
150 === JIRA Project Creation ===
151
152 * Go to the [[JIRA project view>>https://jira.xwiki.org/secure/project/ViewProjects.jspa]]
153 * Click "Create Project" and select "Create with shared configuration" as on:(((
154 {{image reference="jira.png" width="350px"/}}
Vincent Massol 109.1 155 )))
Thomas Mortagne 119.1 156 * Select the "LATEX" project to copy the config from since it's one project that is known to have the right config.
157 * After it's been created it's nice to add a ##1.0## version
158 * Also make sure to check that the Category is set to "XWiki Contributed Projects - Others" (it's located in "Details" or simply click "Edit" on the [[JIRA project view>>https://jira.xwiki.org/secure/project/ViewProjects.jspa]]).
Vincent Massol 94.1 159
Thomas Mortagne 119.1 160 ==== Permissions, Groups & Roles ====
Vincent Massol 112.1 161
Thomas Mortagne 119.1 162 * Contrib committers (##xwiki-contrib## GitHub Organization) must be added to the ##contrib-committers## group
163 * XWiki committers (##xwiki## GitHub organization) must be added to the ##xwiki-committers## group
164
165 When you copy the LATEX jira project you inherit from these rules:
166
167 * Projects must have the ##Committers## role be including ##contrib-committers## and ##xwiki-committers## groups
168 * Projects must have the ##contrib-committers## and ##xwiki-committers## groups added to the ##Administrators## role so that Contrib & XWiki committers can release the projects in JIRA (in addition to being able to release at the SCM level).
169 * Project permissions must be using the ##Committers## role to decide what user are allowed to access.
170 * TODO: Add rules about special contributors.
171
172 = Requesting CI / Snapshot builds for your project =
173
Vincent Massol 126.3 174 XWiki.org has a [[continuous build>>dev:Community.ContinuousBuild]] which builds maven projects each time they are modified on GitHub and put the resulting artifact in our [[snapshots Maven repository>>https://nexus.xwiki.org/nexus/content/groups/public-snapshots/]]. This is useful when you want people using your project as a dependency to continuously benefit from the improvements or to tell users of your Extension try it out before it's released.
Thomas Mortagne 119.1 175
176 To have your project added to the continuous build follow thes steps:
177
178 * First you need to use the XWiki parent pom to have the correct distribution management information. For example for a projects depending on ##xwiki-platform## (See [[Parent POM>>https://github.com/xwiki-contrib/parent]] for more details):(((
179 {{code language="xml"}}
180 <project>
181 ...
182 <parent>
183 <groupId>org.xwiki.contrib</groupId>
184 <artifactId>parent-platform</artifactId>
185 <version>see the building section below to choose the version</version>
186 </parent>
187 ...
188 </project>
189 {{/code}}
Jean-Vincent Drean 7.1 190 )))
Thomas Mortagne 119.1 191 * Add a [[##Jenkinsfile##>>https://jenkins.io/doc/book/pipeline/jenkinsfile/]] to the root of your module. Here's a simple example that should work fine:(((
192 {{code language="groovy"}}
193 /*
194 * See the NOTICE file distributed with this work for additional
195 * information regarding copyright ownership.
196 *
197 * This is free software; you can redistribute it and/or modify it
198 * under the terms of the GNU Lesser General Public License as
199 * published by the Free Software Foundation; either version 2.1 of
200 * the License, or (at your option) any later version.
201 *
202 * This software is distributed in the hope that it will be useful,
203 * but WITHOUT ANY WARRANTY; without even the implied warranty of
204 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
205 * Lesser General Public License for more details.
206 *
207 * You should have received a copy of the GNU Lesser General Public
208 * License along with this software; if not, write to the Free
209 * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
210 * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
211 */
212
213 // It's assumed that Jenkins has been configured to implicitly load the vars/xwikiModule.groovy library which exposes
214 // the "xwikiModule" global function/DSL.
215 // Note that the version used is the one defined in Jenkins but it can be overridden as follows:
216 // @Library("[email protected]<branch, tag, sha1>") _
217 // See https://github.com/jenkinsci/workflow-cps-global-lib-plugin for details.
218
219 xwikiModule {
220 }
221 {{/code}}
222
Vincent Massol 126.2 223 If you wish to see what this ##Jenkinsfile## will do and how to configure it, check the [[xwikiModule source code>>https://github.com/xwiki/xwiki-jenkins-pipeline/blob/master/vars/xwikiBuild.txt]].
Jean-Vincent Drean 6.1 224 )))
Thomas Mortagne 119.1 225
226 {{warning}}
Vincent Massol 130.1 227 If you wish to see your project appear quickly on the [[CI page for XWiki Contrib>>https://ci.xwiki.org/view/Contrib/job/XWiki%20Contrib/]], ping a dev on IRC or on the [[Forum>>https://forum.xwiki.org/c/Dev]]. If you don't, then it'll appear automatically within 24 hours.
Thomas Mortagne 119.1 228 {{/warning}}
229
Simon Urli 122.1 230 = Requesting translation component on l10n.xwiki.org =
231
232 XWiki.org and some contrib projects are using Weblate on l10n.xwiki.org to manage their translations.
Simon Urli 122.2 233 You can ask to have your own project translated on the same platform. Don't forget to follow [[our translations best practices>>dev:Community.DevelopmentPractices#HTranslationBestPractices]] in that case to avoid any issue.
Simon Urli 122.1 234
235 If you are not a committer the easiest way is to ask on the [[Forum>>https://forum.xwiki.org/c/Dev]] by providing the following information:
236
Simon Urli 122.2 237 * the link to the Github repository
238 * the relative path to the translation sources from the root of the repository (if you have several translation sources, indicate them all)
Simon Urli 122.1 239
Simon Urli 122.2 240 If you are a committer the procedure to follow is available on [[XWiki Weblate configuration page>>dev:Community.Weblate Configuration#HHowtoimporttranslationfilesautomatically]].
241
Thomas Mortagne 119.1 242 = Release the project =
243
244 There are 3 main steps to release your project:
245
246 {{toc scope="local"/}}
247
248 == JIRA Release ==
249
250 * If your project is using JIRA, release the version in JIRA and add a new version label for the next version.
251 * If you're using a [[Contrib Parent POM>>https://github.com/xwiki-contrib/parent]] then you can configure your POM to [[auto-release on JIRA>>https://github.com/xwiki-contrib/parent#enable-automatic-jira-release]].
252
253 == Release using Maven ==
254
Vincent Massol 126.3 255 XWiki.org allows you to release your project on the [[XWiki Maven Remote Repository>>https://nexus.xwiki.org]] as long as you follow these steps:
Thomas Mortagne 119.1 256
257 * Use ##org.xwiki.contrib## as ##groupId## in your maven module
Vincent Massol 126.3 258 * Request for an account on [[Nexus>>https://nexus.xwiki.org]] by sending a post on the [[Forum>>https://forum.xwiki.org/c/Dev]], mentioning the username you'd wish to have (you could also mention which extension you're planning to release to provide contextual information).
Thomas Mortagne 119.1 259 * Once you've received your credentials put them in(((
260 ##~~/.m2/settings.xml##
261
262 {{code language="xml"}}
263 <settings>
264 ...
265 <servers>
266 ...
267 <server>
268 <id>xwiki-staging</id>
269 <username>username</username>
270 <password>********</password>
271 </server>
272 ...
273 </servers>
274 ...
275 </settings>
276 {{/code}}
277 )))
278 * If you're using a [[Contrib Parent>>https://github.com/xwiki-contrib/parent]] in your POM under ##<parent>## and if you have configured the JIRA plugin to do automatic releases, make sure to also [[update your ##settings.xml## with JIRA credentials>>https://github.com/xwiki-contrib/parent#enable-automatic-jira-release]].
279 * Put the following configuration in your project(((
280 ##pom.xml##
281
282 {{code language="xml"}}
283 <project>
284 ...
285 <scm>
286 <connection>scm:git:git://github.com/xwiki-contrib/{extensionrepository}.git</connection>
287 <developerConnection>scm:git:[email protected]:xwiki-contrib/{extensionrepository}.git</developerConnection>
288 <url>https://github.com/xwiki-contrib/{extensionrepository}/tree/master</url>
289 </scm>
290 ...
291 </project>
292 {{/code}}
293
Vincent Massol 126.3 294 Where ##{extensionrepository}## is the name of the repository in [[https://github.com/xwiki-contrib/]].
Thomas Mortagne 119.1 295 )))
slauriere 121.1 296 * Release the project with the maven release plugin (notice the ##integration-tests## profile that is needed when there are functional tests but that you should always use since it doesn't harm; the full command is important, otherwise only a portion of the modules will get prepared and thus some will have wrong versions afterwards).(((
Thomas Mortagne 119.1 297 {{code language="none"}}
Vincent Massol 127.1 298 mvn release:prepare -Pintegration-tests,docker -Darguments="-DskipTests" -DskipTests
Thomas Mortagne 119.1 299 {{/code}}
300
301 {{warning}}
302 If you want to skip the enforcer plugin, use:
303
304 {{code language="none"}}
Vincent Massol 127.1 305 mvn release:prepare -Pintegration-tests,docker -Darguments="-DskipTests -Dxwiki.enforcer.skip=true" -DskipTests
Thomas Mortagne 119.1 306 {{/code}}
307 {{/warning}}
308 )))
Vincent Massol 126.3 309 * The released XWiki artifacts are signed ([[http:~~/~~/en.wikipedia.org/wiki/Digital_signature>>https://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.(((
Thomas Mortagne 119.1 310 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).
311
312 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:
313
314 * Overwrite the settings of the gpg plugin in your pom to disable signing:(((
315 {{code}}
316 <profiles>
317 <profile>
318 <id>release</id>
319 <build>
320 <plugins>
321 <plugin>
322 <groupId>org.apache.maven.plugins</groupId>
323 <artifactId>maven-gpg-plugin</artifactId>
324 <configuration>
325 <skip>true</skip>
326 </configuration>
327 </plugin>
328 </plugins>
329 </build>
330 </profile>
331 </profiles>
332 {{/code}}
333 )))
334 * Configure your setup to sign properly. To do that, you will have to:
Vincent Massol 126.3 335 ** 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>>https://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.
Thomas Mortagne 119.1 336 ** 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(((
337 {{code}}
338 ...
339 <profile>
340 <id>xwiki</id>
341 <properties>
342 <gpg.passphrase>PASSWORD</gpg.passphrase>
343 </properties>
344 ...
345 {{/code}}
346 )))
347 )))
348 * You're done now, you can go on releasing(((
349 {{code language="none"}}
Vincent Massol 128.1 350 mvn release:perform -Pintegration-tests,docker
Thomas Mortagne 119.1 351 {{/code}}
352
353 {{info}}
354 On Windows you can use this command to successfully perform the release:
355
356 {{code language="none"}}
Vincent Massol 128.1 357 mvn release:perform -Pintegration-tests,docker -Darguments="-Dgpg.passphrase="YourGpg4winPassword" -Dxwiki.enforcer.skip=true"
Thomas Mortagne 119.1 358 {{/code}}
359
Vincent Massol 126.3 360 but be careful to replace "YourGpg4winPassword" with the actual password chosen when creating a GPG key with [[Gpg4win>>https://www.gpg4win.org/]].
Thomas Mortagne 119.1 361 {{/info}}
362
363 {{info}}
364
365 On Windows, when you have this issue:
366
367 {{code language="none"}}
368 gpg: no default secret key: secret key not available
369 gpg: signing failed: secret key not available
370 {{/code}}
371
372 * Add this to your settings.xml:
373
374 {{code}}
375 ...
376 <profile>
377 <id>xwiki</id>
378 <properties>
379 <gpg.keyname>your_user_id</gpg.keyname>
380 <gpg.homedir>path_to_your_key</gpg.homedir>
381 <gpg.passphrase>PASSWORD</gpg.passphrase>
382 </properties>
383 ...
384 {{/code}}
385
386 {{/info}}
387
388 {{info}}
389 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.
390 {{/info}}
391
392 {{warning}}
393 If the application has also a special module that execute UI tests and you want to release the modules, but not run the tests, you should:
394
395 {{code language="none"}}
396 mvn release:perform -Pintegration-tests -Darguments="-DskipTests -Pintegration-tests" -DskipTests
397 {{/code}}
398
399 {{/warning}}
400 )))
401 * Note that you'll need to push the changes done by the release plugin: {{code}}git push origin master{{/code}}
Vincent Massol 126.3 402 * By default the extension will be automatically released on ##nexus.xwiki.org##. In case you have configured your extension's POM so that it's not the case then ask for someone (on the [[Forum>>https://forum.xwiki.org/c/Dev]] or on IRC) to validate your release from the staging repository on [[Nexus>>https://nexus.xwiki.org]] to make your extension available on ##nexus.xwiki.org##. Alternatively if you've been granted the permissions you can do this yourself by understanding [[Nexus Staging>>https://books.sonatype.com/nexus-book/reference/staging-repositories.html]]. To perform promotion do the following:
Thomas Mortagne 119.1 403 ** Select the repository to validate in the Staging Repositories list
404 ** Click the "Close" button to close it. Wait a few seconds since it's done asynchronously.
405 ** Make sure to test your extension from the closed staging repo first since a released repo cannot be removed!
406 ** 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.
407 * After that your release will be available for download on ##nexus.xwiki.org## and anyone will be able to use it as a dependency for his own project
408
409 == Documentation ==
410
411 * 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 sections for more.
Vincent Massol 129.1 412 * Announce the new release on the [[Forum>>https://forum.xwiki.org/c/News]] (in the News & Events category).
413 ** Use the ##contrib## and ##release## tags
Thomas Mortagne 119.1 414
415 = Recovering from a failed Release =
416
417 It may happen that the ##release:perform## fails. In this case you'll want to rollback, fix the problem and release again. Maven generates temporary files in your module's directory. Don't remove them! :)
418
419 To rollback you need to call the following:
420
421 {{code language="none"}}
422 mvn release:rollback
423 {{/code}}
424
425 {{warning}}
Vincent Massol 126.3 426 The document for the [[##release:rollback## mojo>>https://maven.apache.org/maven-release/maven-release-plugin/examples/rollback-release.html]] says that currently the deletion of the created tag is not implemented. Thus even if you see the rollback call you will still need to perform step 2 of the manual process below.
Thomas Mortagne 119.1 427 {{/warning}}
428
Vincent Massol 126.3 429 Now if you have already deleted those files, don't panic! It's still easy to recover. You'll just need to do manually [[what the ##release:rollback## does>>https://maven.apache.org/maven-release/maven-release-plugin/examples/rollback-release.html]]:
Thomas Mortagne 119.1 430
431 * Rollback the changes done by the ##release:prepare## call by reverting the changes in Git
432 * Remove the local and remote tag created by the ##release:prepare## call ({{code language="none"}}git tag --delete the_local_tag{{/code}} and {{code language="none"}}git push origin :the_remote_tag{{/code}}).
433
434 = Publishing on extensions.xwiki.org =
435
Oana-Lavinia Florean 131.1 436 The first step is to [[release>>#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.
Thomas Mortagne 119.1 437
438 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).
439
440 {{info}}
441 If you have already imported your Extension and you've just published a new version in nexus.xwiki.org and you wish to update the version seen on extensions.xwiki.org you should know that this is automatically done every night by a scheduler job so you don't have to do anything. However if you wish to force it, go to your extension page and click the refresh icon located at the top right corner of that page.
442 {{/info}}
443
444 = Implementing your Maven build =
445
Vincent Massol 128.5 446 See the [[Creating Extensions tutorial>>platform:DevGuide.CreatingExtensions.WebHome]].
Thomas Mortagne 119.1 447
448 = Application Design =
449
450 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.
451
452 * 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:(((
453 {{image reference="spaces.png"/}}
454 )))
455 * 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(((
456 {{image reference="hidden.png"/}}
457 )))
458 * Make sure you add a User Interface Extension (UIX) for the Application Panel extension point. This registers your application into the Application Panel:(((
459 {{image reference="applications-panel.png"/}}
460
461 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:
462 {{image reference="application-uix.png"/}}
463
464 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):
465
466 {{code}}
467 {{include document="XWiki.UIExtensionSheet" /}}
468 {{/code}}
469 )))
470
471 = Documenting =
472
473 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.
474
475 {{warning}}
476 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...
477 {{/warning}}
478
479 Verify the value of the fields filled automatically by the import, namely:
480
481 * The page name
482 * The description
483 * The authors
484
485 If they're wrong you'll need to publish a new version of your extension and re-import it.
486
487 Edit it and provide nice user-friendly documentation. We recommend the following elements to be present:
488
489 * Description of what the extension does and the features it has (briefly). Provides an overview screenshot if it makes sense.
490 * Usage: explains how to use it
491 * Document each feature with some text but very importantly with a screenshot
492 * Fill the "General Compatibility" section with the minimal version of XWiki your extension requires to be installed
493 * Fill the "Tested On" section with the versions of XWiki you've tested your extension on. Never remove any existing data from this section since they represent past tests and we need to keep the history.
494
495 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).
496
497 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.
498
499 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!).

Get Connected