Development Practices

Development Practices

XWiki development follows several rules listed below. If you're a Committer or if you simply wish to contribute please take the time to read them as you're expected to follow these rules.

Continuous Integration

XWiki has a Continuous Integration setup to ensure XWiki is building at all times.

We use the following tools:

• Maven2 is used for building XWiki
• TeamCity is used as our Continuous Integration (CI) tool (set up at http://teamcity.xwiki.org/)
• Fisheye is used to browse our Subversion repository (set up at http://fisheye.xwiki.org)

Automated Builds

XWiki has an automated builds and developers are asked to use it on their local machines to prove that their changes work before committing them to the Source Repository. See the Building page for more details.

Copyright header in source files

All files (including configuration files) must have the following copyright statement.

For Java files

/*
 * 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.
 */

For XML files

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

Coding Conventions

See the Code Style page.

Iteration Driven Development (IDD)

General rule:

• Whenever someone commits something to the Source Repository he/she has to put the reference to the JIRA issue number (e.g. XWIKI-XXX) in the commit message.
• Of course this shouldn't be done for any trivial things like adding a small javadoc, renaming a single variable, cosmetic changes, svn ignore, etc.

• When you plan to work on something, create a JIRA issue and assign it to yourself or simply assign an existing JIRA issue to yourself if one already exists
• Implement it
• Commit it with the JIRA issue number in the commit message
• Close the JIRA issue

• Implement something
• When you want to commit it you realize you don't have any JIRA issue to put in the commit message so don't commit.
• Create the JIRA issue
• Commit with the JIRA number in the commit message

• One consistent way to manage all the work to be done on the XWiki proejct. It also means there's no unaccounted work, meaning anyone can go to JIRA and query it and see what everyone has been working on.
• Automated release notes/change logs. When we release a version we can simply do a JIRA extract and it'll give the full change log of what happened. This is really important for our users to see what has been done when in XWiki.
• Tracability. When you use the JIRA issue number in your commit, the JIRA subversion plugin can show the modified files directly from JIRA. This is quite useful later on, when someone is looking at a JIRA issue and wants to see what was modified. In addition Fisheye is also integrated with JIRA and when you browse the source repository you can see the JIRA issue associated with files.

Additional tips for practicing IDD

• If you want to know whether you should create a JIRA issue or not, ask yourself the question: "is my change going to affect any user or any plugin developer in any way"? If the answer is yes then you must create a JIRA issue
• You shouldn't create a bug issue for a new feature that you or someone else has implemented in the current version under development. Whatever fix you do must be against the existing JIRA issue for that bug/feature. The idea here is that the changelog must be as meaningful as possible.
• When you create a JIRA issue always take the time to put a nice title for the issue. The title must be understandable by a user so don't describe the issue technically but rather in what way it affects users. For example don't say "Fix the addXXX API to return an Array List" but rather "Allow creating several pages at once".

JIRA Practices

• IDD: See above
• Issues that are closed with "Won't fix", "Duplicate", "Cannot reproduce" or "Incomplete" we must set the "Fix For" field to "unknown" so that they don't appear in the release notes, as JIRA doesn't make the distinction visible and this causes confusion.

Using bird names for Skins

We have decided to name XWiki official skins using bird names. We are currently renaming the existing skins. Any new skin must use a bird name. It's recommended to send a proposal to the list whenever a new skin has to be named.

Here are some potential ideas of names:

• Dove
• Emu
• Kiwi
• Grasswren
• Condor
• Warbler
• Kestrel
• Redtail
• Dodo
• Pigeon
• Albatross
• Booby
• Sparrow
• Blackbird
• Toucan
• Parrot
• Peacock
• Finch
• Wren
• Crow
• Turkey
• Thunderbird
• Piasa (a local phenomenon, from a primitive painting on the cliffs on the eastern shore of the Mississippi, attributed to the Piasa tribe, which looks rather like a griffin)
• Thunder Chicken
• Kingfisher
• Swallow

Subversion Practices

Applying a contributor's patch

Please use the following commit log message template:

XWIKI-XXX: <description of issue here>
Patch submitted by <contributor's name>
Reviewed by <reviewer's name>

<additional comments here>

This gives credit to the contributor.

Also make sure to add the contributor's name to the Contribution page.

This is important to give proper recognition to our contributors.

Subversion configuration and line endings

It's important that everyone's subversion client is configured properly, especially for line endings. See http://www.apache.org/dev/version-control.html#https-svn and http://svnbook.red-bean.com/en/1.0/svn-book.html#svn-ch-7-sect-2.3.5 for more details.

Please add the content of the following file to your Subversion config file: http://www.apache.org/dev/svn-eol-style.txt

Backward Compatibility

We must pay attention to backward compatibility. We have decided to use AspectJ Aspects for implementing backward-compatibility, as described in this blog post.

This allows us to get the following advantages:

• We keep backward compatibility
• We get clean code and this allows us to get also a clean Javadoc since the javadoc is applied without the Aspects being weaved
• All backward compat code is gathered in a single place
• It's easy to remove deprecation when required