XWiki Contrib
- Contrib Project List
- Hosting tools
- Contributing to an existing project
- Why join XWiki Contrib
- Development Practices
- Requesting a project
- Requesting CI / Snapshot builds for your project
- Requesting translation component on l10n.xwiki.org
- Release the project
- Recovering from a failed Release
- Publishing on extensions.xwiki.org
- Implementing your Maven build
- Retire a Contrib project
- Application Design
- Documenting
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.
Contrib Project List
The full list of Contrib projects is available on GitHub
Note that projects not having an active maintainer are moved to the Attic (The definition of "active" is left to the community and anyone can propose to move inactive projects to the Attic).
Hosting tools
The project hosting forge can provide contributors with some or all of the following tools:
- A GitHub repository, under https://github.com/xwiki-contrib
- 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.
- 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.
- A CI job on https://ci.xwiki.org for building the project automatically on each commit (more specifically see XWiki Contrib jobs).
- A Sonar project report on https://sonar.xwiki.org to analyze the project's quality with various metrics.
- Translations, under the l10n platform.
- There's no dedicated Forum. For the moment, all the projects share the Development category of the forum, but if a project becomes too active for it, a dedicated forum Category can be requested.
- There's no dedicated chat room, the main #xwiki chat room must be used, but if a project becomes too active for it, a dedicated chat room can be requested.
Contributing to an existing project
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), introducing yourself and explaining what you wish to do. Make sure to create an account on GitHub and mention this id in the post 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).
- You get some tools setup for your project (GitHub repository, Issue tracker, Wiki pages)
Development Practices
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(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.
Requesting a project
The contrib project is open for anyone who wish to start a new project. Simply send a post on the Forum (dev category) 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).
Choosing the name
When picking the GitHub name please use a single word (e.g. forum). However, sometimes that is not descriptive enough, so you can either use multiple words next to each other (e.g. filemanager) if that makes sense and looks natural enough or, if not, you should separate the words with a dash (e.g. multiselect-suggest). Whatever you decide, please try to keep it as short and descriptive as possible.
Try to avoid using names that would not work well if some new Maven modules need to be added in the future (e.g. avoid using figure-macro since there could be new modules added that wouldn't be macros, such as API, Application (XAR) or other module types. In short, this means having a "business" name, not related to the extension type.
If there's already a repo with the name you want to use, consider adding your code as a sub-module if it fits the same domain and can be released together (same release lifecycle). If it doesn't fit, use a different name (adding a qualifier or a different name altogether).
Special cases:
- icon-themes. This is a reserved name and it's also the name of a special repository containing all 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.
- color-themes. This is a reserved name and it's also the name of a special repository containing all 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.
Hint: When in doubt, have a look at existing repository names for inspiration but only for repos created after the 2023-05-16 since the naming strategy was changed at that date!
Always avoid using the xwiki- prefix since this one is used by XWiki GitHub organization repositories (i.e. Core modules). You should also avoid using it as a suffix since all Contrib projects are related to XWiki.
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:
<Short Description of Extension, taken from the description element in the pom.xml>
* Project Lead: [<info taken from the jira project, e.g. Vincent Massol>](<url to user profile on xwiki.org>)
<if single extension page>
* [Documentation & Download](<url on e.x.o, e.g. https://extensions.xwiki.org/xwiki/bin/view/Extension/Flash+messages+application>)
</if single extension page>
<if several extension pages>
* Documentation & Downloads:
* [<pretty name of page1, e.g. My App API](<url1 on e.x.o)
...
* [<pretty name of pageN, e.g. My App API](<urlN on e.x.o)
</if several extension pages>
* [Issue Tracker](<url on jira.xwiki.org, e.g. https://jira.xwiki.org/browse/XAFLASHM>)
* Communication: [Forum](<url, e.g. https://forum.xwiki.org></url>), [Chat](<url, e.g. https://dev.xwiki.org/xwiki/bin/view/Community/Chat>)
<if link pointing to all dev practices>
* [Development Practices](<URL pointing to a site defining the list of practices to be followed by contributors when contributing on this project>)
</if link pointing to all dev practices>
<if no single link pointing to all dev practices>
* Development Practices:
* <best practice 1, possibly with some link>
...
* <best practice N, possibly with some link>
</if no single link pointing to all dev practices>
* Minimal XWiki version supported: <taken from the pom.xml, e.g. XWiki 6.4.7>
* License: <license,taken from the pom.xml, e.g. LGPL 2.1>.
<if translation is used>
* [Translations](<url on l10n to translations for this extension>)
</if translation is used>
<if translation is not used>
* Translations: N/A
</if translation is not used>
<if sonar is used>
* [Sonar Dashboard](<url to the project’s dashboard on sonar.xwiki.org, e.g. https://sonar.xwiki.org/dashboard/index/10464>)
</if sonar is used>
<if sonar is not used>
* Sonar Dashboard: N/A
</if sonar is not used>
<if ci is used>
* 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/)
</if ci is used>
<if ci is not used>
* Continuous Integration Status: N/A
</if ci is not used>
<optional>
## Whatever
...
</optional>
Here's an example.
For XWiki Admins
You have to create 2 things:
- A GitHub repository
- a JIRA project
Optionally, if the project is large enough:
- A matrix room
GitHub Repository Creation
Perform the following steps:
- Navigate to the GitHub Template Repository and click the "Use this template" dropdown and select "Create a new repository"
- Select xwiki-contrib as the owner and make sure it's public. Choose a proper name and description (see above). Then click "Create repository from template".
- Go the new repository settings and perform the following changes:
- Uncheck the "wiki", "issues" and "projects" checkboxes
- Add the xwikiorg group in the "Manage Access" settings. Make sure to select the "Write" permission (it's "Read" by default).
- Under "Notifications", add the notifications AT xwiki DOT org email
JIRA Project Creation
- Go to the JIRA project view
- Click "Create Project" and select "Create with shared configuration" as on:
- Select the "LATEX" project to copy the config from since it's one project that is known to have the right config.
- After it's been created it's nice to add a 1.0 version
- 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).
Permissions, Groups & Roles
- Contrib committers (xwiki-contrib GitHub Organization) must be added to the contrib-committers group
- XWiki committers (xwiki GitHub organization) must be added to the xwiki-committers group
When you copy the LATEX jira project you inherit from these rules:
- Projects must have the Committers role be including contrib-committers and xwiki-committers groups
- 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).
- Project permissions must be using the Committers role to decide what user are allowed to access.
- TODO: Add rules about special contributors.
Matrix room
- Click on the + button to create a room
- Select "New Room"
- Define a name and a topic
- Select public room
- Define the room address (which must be agreed on during the matrix room forum request)
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("XWiki@<branch, tag, sha1>") _
// See https://github.com/jenkinsci/workflow-cps-global-lib-plugin for details.
xwikiModule {
}For more examples and details, check the Continous Integration documentation (and if you wish to see what this Jenkinsfile will do and how to configure it, check the xwikiModule source code).
Requesting translation component on l10n.xwiki.org
XWiki.org and some contrib projects are using Weblate on l10n.xwiki.org to manage their translations.
You can ask to have your own project translated on the same platform. Don't forget to follow our translations best practices in that case to avoid any issue.
If you are not a committer the easiest way is to ask on the Forum by providing the following information:
- the link to the Github repository
- the relative path to the translation sources from the root of the repository (if you have several translation sources, indicate them all)
If you are a committer the procedure to follow is available on XWiki Weblate configuration page.
Release the project
There are 3 main steps to release your project:
Release using Maven
XWiki.org allows you to release your project on the XWiki Maven Remote Repository as long as you follow these steps:
- Use org.xwiki.contrib as groupId in your maven module
- Request for an account on Nexus by sending a post on the Forum, mentioning the username you'd wish to have (you could also mention which extension you're planning to release to provide contextual information).
- Once you've received your credentials put them in
~/.m2/settings.xml
<settings>
...
<servers>
...
<server>
<id>xwiki-staging</id>
<username>username</username>
<password>********</password>
</server>
...
</servers>
...
</settings> - If you're using a 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.
- Put the following configuration in your project
pom.xml
<project>
...
<scm>
<connection>scm:git:git://github.com/xwiki-contrib/{extensionrepository}.git</connection>
<developerConnection>scm:git:[email protected]:xwiki-contrib/{extensionrepository}.git</developerConnection>
<url>https://github.com/xwiki-contrib/{extensionrepository}/tree/master</url>
</scm>
...
</project>Where {extensionrepository} is the name of the repository in https://github.com/xwiki-contrib/.
- 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).mvn release:prepare -Pintegration-tests,docker -Darguments="-DskipTests" -DskipTests
- The released XWiki artifacts are signed (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.
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:<profiles>
<profile>
<id>release</id>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-gpg-plugin</artifactId>
<configuration>
<skip>true</skip>
</configuration>
</plugin>
</plugins>
</build>
</profile>
</profiles> - Configure your setup to sign properly. To do that, you will have to:
- 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...
<profile>
<id>xwiki</id>
<properties>
<gpg.passphrase>PASSWORD</gpg.passphrase>
</properties>
...
- 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
- Overwrite the settings of the gpg plugin in your pom to disable signing:
- You're done now, you can go on releasingmvn release:perform -Pintegration-tests,docker -Darguments="-DskipTests -Pintegration-tests,docker" -DskipTests
- Note that you'll need to push the changes done by the release plugin: git push origin master
- 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 or on IRC) to validate your release from the staging repository on Nexus 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. 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 nexus.xwiki.org and anyone will be able to use it as a dependency for his own project
JIRA Release
Follow these steps:
- If you're using a Contrib Parent POM and you have configured your POM to auto-release on JIRA.
- All you need to do is add the next version label in JIRA.
- If not, you'll need to manually release the version in JIRA, and add a new version label for the next version.
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.
- Announce the new release on the XWiki.org Blog.
- Use the following templates:
- For the main content:The [[(extension name)>>doc:extensions:Extension.(extension spaces).WebHome]] [[(extension version)>>doc:extensions:Extension.(extension spaces).WebHome||anchor="H(extension version)"]] has been released.
(text of the release). - For the summary content:The [[(extension name)>>doc:extensions:Extension.(extension spaces).WebHome]] [[(extension version)>>doc:extensions:Extension.(extension spaces).WebHome||anchor="H(extension version)"]] has been released. (text of the release).
- For the main content:
- Use the Releases, Extensions and Contrib categories
- Set the What's New categories so that the announcement is sent to all XWiki instances around the world. To do that:
- Make sure to review your text for typos and quality of English (you can ask for a review on the #xwiki chat for example).
- Set the What's New for XWiki category
- Set the What's New for XWiki: Admin User category (since it's Admin who upgrade or install extensions)
- Set the What's New for XWiki: Extension category (since contrib is about extensions)
- If you don't have permissions to create blog posts, please ask on the Matrix chat or on the forum, in the Other category.
- Use the following templates:
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:
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:
- 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 tag --delete 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).
Implementing your Maven build
See the Creating Extensions tutorial.
Retire a Contrib project
See Retiring a module.
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):
{{include document="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.
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 to follow the Documentation guide. For example take a special care to follow the Image best practices (use the {{image}} macro and don't take large screenshots as mentioned).
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!).