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!
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.patchwhere 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 jspwiki.org and attach your module there. Good places to start from are ContributedCode, ContributedLocalizations, ContributedPlugins, ContributedJSPWikiTags, and ContributedTemplate.