So you have some nice code which you would like to contribute to JSPWiki? This is much appreciated! Please do send the JSPWiki community your stuff - but do not expect everything to end in the JSPWiki distribution. Please see below on how to do the submission.

Submitting a Patch#

Whenever you wish to contribute a patch to JSPWiki, please do the following

  • Create a new Issue in JIRA, and attach your patch to it
  • Be very explicit against which version of JSPWiki the patch is. We can't guess!

Patch guidelines#

To make it more probable that your patch gets approved, please observe these guidelines before submitting patches:

Keep a single issue in a single patch and a single Issue

Please, noo "this patch does xyzzy and foo and thingy"! Each patch should be for one feature.

Submit short patches only

Please, really. The shorter, the better. If you have made several changes, then try to separate them into multiple patches - it's much, MUCH easier to understand what is going on!

Use diff -u

Please use the unified diff format instead of the standard diff format. This makes the patch easier to read before applying, and gives the developers a better idea what is changed.

Please do not send changed files - always send diffs. We will ignore full files.

With Eclipse, for example, creating a diff (or in Eclipse-talk, a patch) is trivial. Choose Team->Create Patch.

With command line tools, do

svn diff >jspwiki-125.patch
where jspwiki-125 is the jira issue.

Name the patches properly

Each patch should be named as jspwiki-xxx.patch, where xxx denotes the JIRA issue number. You may add other notes to it, like your name (e.g. jspwiki-122-janne.patch), or add a short description (jspwiki-122-remove_quotes.patch).

Write Unit Tests

If you add new classes, new methods, or do anything new, please consider adding a UnitTest or two to test your class. It'll make it much easier to maintain those classes in the long run.

Run Unit Tests

When you make changes, do not forget to run "ant tests" before submitting any patches. Any patch that breaks current UnitTests is likely to be rejected at the speed of thought unless a good explanation is attached :-).

Don't change layout

If you choose to change layout (that is, indentation, location of curly braces, etc), then please make a separate patch from it. It is quite tedious to try and figure out which parts of a patch change actual functionality and which parts are just eye-candy.

(Yes, code beautifiers exist. But in general they tend to break havoc with your diffs anyway...)

Use coding conventions

JSPWiki code uses the JSPWiki coding standard, obviously :-). It's a derivative of the Avalon Coding Standards, and is somewhat incompatible with the Java Coding Conventions recommended by Sun Microsystems. This page details some of the reasoning behind the differences.

Please DO follow these instead of using your own preferred conventions, because

a) We'll have to convert them to the JSPWiki coding standard anyway, and
b) they make code more difficult to understand for people who are used to the code base.

Remember, the more work you make us do, the less probable is that your code gets approved. The fastest patch so far to get included in the main tree took me about 60 seconds to read through, approve, drop in and test :-).

Upload your code to the proper place

If you wish to have your code added to the JSPWiki core, you should go to the issue tracker, create an issue, and add your patch there.

Contributing a plugin or some other module#

If you are developing a plugin or some other JSPWiki module (e.g. a new translation), you should create a new page in and attach your module there. Good places to start from are ContributedCode, ContributedLocalizations, ContributedPlugins, ContributedJSPWikiTags, and ContributedTemplate.

Add new attachment

Only authorized users are allowed to upload new attachments.
« This page (revision-52) was last changed on 25-Sep-2010 23:42 by Wouter Van daele