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.

Hosting tools

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).

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.

A Mailing list for your project. Note that for the moment, all the projects share common mailing lists.

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.

Contributing to an existing project

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), 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!

Why join XWiki Contrib

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:

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.

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).

Requesting a project

The contrib project is open for anyone who wish to start a new project. Simply send us an email at devs AT xwiki.org using "[Contrib]" at the beginning of your email's subject (after having subscribed). 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 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).

Choosing the name

When picking the GitHub name please follow the existing conventions:

application-<xxx> for apps

macro-<xxx> for macros only (if you project provides a macro but also provides other wiki pages then it's considered an app)

api-<xxx> for APIs only (same as for macro, if it contains UI as well, then you should call it an app instead)

displayer-<xxx> for custom displayers

syntax-<xxx> for rendering syntaxes

authenticator-<xxx> for authenticators

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.

Please try to avoid using the xwiki- prefix since this one is used by XWiki GitHub organization repositories (i.e. Core modules).

README.md Template

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:

# <Pretty name of Extension, e.g. Flash Messages Application>

<Short Description of Extension, taken from the description element in the pom.xml>

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). Use the "Markdown (with view)" and "unprotected" links.

For XWiki Admins

You have to create 2 things:

A GitHub repository

a JIRA project

GitHub Repository Creation

When creating a new xwiki-contrib repository on GitHub please make sure to:

Uncheck the "wiki" and "issues" checkboxes in the settings

Add the xwikiorg group in the Collaborators settings

Add an email service pointing to notifications AT xwiki DOT org for notifications

JIRA Project Creation

Requesting CI / Snapshot builds for your project

XWiki.org has a continuous build which builds maven projects each time they are modified on GitHub and put the resulting artifact in our snapshots Maven repository. 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.

To have your project added to the continuous build follow thes steps:

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 for more details):

<project>...<parent><groupId>org.xwiki.contrib</groupId><artifactId>parent-platform</artifactId><version>see the building section below to choose the version</version></parent>...</project>

Add a Jenkinsfile to the root of your module. Here's a simple example that should work fine:

/* * See the NOTICE file distributed with this work for additional * information regarding copyright ownership. * * This is free software; you can redistribute it and/or modify it * under the terms of the GNU Lesser General Public License as * published by the Free Software Foundation; either version 2.1 of * the License, or (at your option) any later version. * * This software is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public * License along with this software; if not, write to the Free * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA * 02110-1301 USA, or see the FSF site: http://www.fsf.org. */

// It's assumed that Jenkins has been configured to implicitly load the vars/xwikiModule.groovy library which exposes// the "xwikiModule" global function/DSL.// Note that the version used is the one defined in Jenkins but it can be overridden as follows:// @Library("[email protected]<branch, tag, sha1>") _// See https://github.com/jenkinsci/workflow-cps-global-lib-plugin for details.

Release using Maven

Request for an account on Nexus by sending a mail to the Developer's list mentioning the username you'd wish to have (you could also mention which extension you're planning to release to provide contextual information).

The signing maven plugin is configured in the toplevel pom ( <groupId>org.xwiki.commons</groupId><artifactId>xwiki-commons</artifactId> ) 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 ( mvn help:effective-pom ) and check if the gpg maven plugin is there (maven-gpg-plugin).

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:

Overwrite the settings of the gpg plugin in your pom to disable signing:

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 (gpg --gen-key, read the man page if you want to know more about the options). On Windows you can use Gpg4win, while on Mac you have the GPG Suite. If you don't know what to fill in for the options requested by the tool, keep the defaults.

Tell maven the passphrase of this key (the one you entered upon key generation), either in the command line when performing the release mvn release:perform -Darguments=-Dgpg.passphrase=PASSWORD or set it in your maven settings.xml like this

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.

If the application has also tests and you want to release the modules, but not run the tests, you should:

Ask for someone (on the devs mailing list or on IRC) to validate your release from the staging repository on Nexus 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. To perform promotion do the following:

Select the repository to validate in the Staging Repositories list

Click the "Close" button to close it. Wait a few seconds since it's done asynchronously.

Make sure to test your extension from the closed staging repo first since a released repo cannot be removed!

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.

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

Documentation

Update the documentation for your project (or create it if there's none) on the Extensions Wiki and make sure to add release notes information. See the next sections for more.

Recovering from a failed Release

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!

To rollback you need to call the following:

mvn release:rollback

The document for the release:rollback mojo says that currently the deletion of the created tag is not implemented. Thus even if you se the rollback call you may still need to perform step 2 of the manual process below.

Rollback the changes done by the release:prepare call by reverting the changes in Git

Remove the local and remote tag created by the release:prepare call (git branch -d the_local_tag and git push origin :the_remote_tag).

Publishing on extensions.xwiki.org

The first step is to release your extension in the XWiki Maven Remote Repository. Then go the Extension wiki home page and click on the Import 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.

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).

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.

Implementing your Maven build

Application Design

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.

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:

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

Make sure you add a User Interface Extension (UIX) for the Application Panel extension point. This registers your application into the Application Panel:

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:

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):

{{includedocument="XWiki.UIExtensionSheet"/}}

Documenting

After you've published your extension in the XWiki Maven Remote Repository, import it on extensions.xwiki.org (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.

If you've already created the page on extensions.xwiki.org 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...

Verify the value of the fields filled automatically by the import, namely:

The page name

The description

The authors

If they're wrong you'll need to publish a new version of your extension and re-import it.

Edit it and provide nice user-friendly documentation. We recommend the following elements to be present:

Description of what the extension does and the features it has (briefly). Provides an overview screenshot if it makes sense.

Usage: explains how to use it

Document each feature with some text but very importantly with a screenshot

Fill the "General Compatibility" section with the minimal version of XWiki your extension requires to be installed

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.

Make sure that you add documentation for your extension as soon as it's published on extensions.xwiki.org. Otherwise nobody is going to start using it and people will start wondering what it's about.

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!).