[{TableOfContents}]\\\

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|JSPWikiDownload].  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|https://issues.apache.org/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|JSPWikiCodingStandard] 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|https://issues.apache.org/jira/browse/JSPWIKI], 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].