Contributing

1. Give us your Feedback
2. Help other users
   1. Strategies for answering questions
3. Spread the word
4. Testing
5. Translations
6. Documentation
7. Share your code
8. Fixing bugs or new Features/Improvements
   1. Patch acceptance criteria
   2. Coding rules
   3. Creating and submitting a patch

We're always looking for contributions! Here are some ways to participate in XWiki's development.

Give us your Feedback

Do you have a great idea? Just tell us! Send your feedback to the user or developer mailing lists. The feedback could be also about something that does not work, something that could be improved, a feature you'd like to see, etc. Or simply it could be that you're a happy user. Letting us know that helps a lot!

Help other users

Have you gained some experience with XWiki? How about sharing your experience with others? Answer emails on the user mailing list.

Strategies for answering questions

Here's a good strategy that improves the XWiki documentation on xwiki.org:

1. someone (A) asks a question on a xwiki list
2. someone (B) knows the answer
3. B verifies that the answer can be found on xwiki.org and if so gives a link to it in the reply to A
4. If the answer is not found on xwiki.org, then B adds it (*) and in his reply to A he provides a link to the answer (see the Documentation chapter below for some tips)

In this manner we all enrich the XWiki documentation and it'll only take marginally longer to answer questions. The next time someone asks the question again we can simply point him/her to the location on xwiki.org

What happens otherwise is that people will give very long and elaborate answers with lots of knowledge/wisdom in them. After that another person comes in, asks the same question and we answer again, etc. The results are:

• the xwiki.org documentation is not better
• overall as a team we are less efficient 

Spread the word

Do you like XWiki? Spread the word about it! In any way you would prefer, like Tweets, Articles, Blogs, Books, Talks at conferences, Discussion with colleagues, etc.

Testing

Test new XWiki versions and report bugs in JIRA.

Translations

Is XWiki not available in your native language? Are current translations not good enough or just not complete? By contributing to the Translation Wiki you can improve that.

Documentation

Not satisfied with the XWiki documentation? Look at the Documentation Guide and help us improve it. One difficulty is to find the right location for new documentation. So here are a few tips:

• Add code snippets to the Code Zone
• Add explanations on how to use XWiki to the related Features guide pages
• Add development explanations to the related Developer guide's pages
• Add configuration and administration explanations to the related Administration guide's pages
• Add other explanations to the FAQ

Share your code

Have you developed great applications, macros etc.? Share them with others on the Code Zone.

Fixing bugs or new Features/Improvements

Have you fixed a boring bug or added a new feature or improved an existing one? Let us know by sending code patches.

Are you looking for a place to start? Look at Paper Cuts. These are easy to fix.

Patch acceptance criteria

There are a number of criteria that a patch will be judged on:

• Whether it works and does what is intended. This one is probably obvious!

• Whether it fits with the spirit of the project. Some patches may be rejected as they take the project in a different direction from that which the current development community has chosen. This is usually discussed on an issue well before a patch is contributed. So if you are unsure about submitting a patch please discuss it there or on the mailing lists first. Feel free to continue discussing it (with new justification) if you disagree, or appeal to a wider audience on the mailing lists.

• Whether it contains tests. It is expected that any patches relating to functionality will be accompanied by unit tests and/or integration tests. It is strongly desired (and will be requested) for bug fixes too, but will not be the basis for not applying it. At a bare minimum, the change should not decrease the amount of automated test coverage. As a community, we are focusing on increasing the current coverage, as there are several areas that do not receive automated testing.

• Whether it contains documentation. All new functionality needs to be documented for users, even if it is very rough for someone to expand on later. While rough is acceptable, incomplete is not. As with automated testing, as a community we are striving to increase the current coverage of documentation.

Above all, don't be discouraged. These are the same requirements the current Committers should hold each other to as well.
And remember, your contributions are always welcome!

Coding rules

If you submit a patch you need to follow these rules:

• Put the correct Copyright in the files.
• Ensure that your code passes the build. Note that the build contains some Checkstyle checks that your code must pass.
• Ensure that you have unit tests and/or integration tests.
• Use the same code formatting as the existing code.
• Create an issue in JIRA and attach your patch to it.
• Create documentation for what you have added.
• Add your name on the Hall Of Fame page.

In addition if you plan to contribute big patches that impact existing code, we recommend discussing it on the mailing list first.

Creating and submitting a patch

When you have either completed a JIRA issue, or just want some feedback on the work you have done, create a patch and attach the patch to the JIRA issue in question. We have a couple of guidelines when creating patches:

• Always create the patch from the root of the project.
• Always provide a single patch and not several diff files. If you're adding new files, svn add them first so that they appear within the single patch file.
• If this was a new piece of work without a JIRA issue, create a JIRA issue for it now.
• Attach the patch to the JIRA issue you were working on (do not paste its content in a comment though). When adding the patch add a comment to the issue explaining what it does. Shortly after, someone will apply the patch and close the issue.

An example on how to create a patch from the command line:
$ svn diff > XWIKI-123-something.patch

If you are picking up an issue with an existing patch attached to the issue you can apply the patch to your working directory directly from JIRA like this. The wget and patch commands will only be available if you are on a UNIX platform or using Cygwin on Windows.

If the patch is in a local file "XWIKI-123.patch" and you want to apply that use this command:

A couple of notes:

• If you are using another tool for creating patches, make sure that the patch doesn't include absolute paths. Including absolute paths in the patch will make it useless for us as we most likely don't have the same directory structure as you.
• Put license headers in newly created files (java classes, pom files, etc).
• Make sure that you follow our code style.