Anyone can contribute
That's right, we always want to hear from people with
contributions to the code,
the documentation, the website, and bug reports.
The rest of this document outlines the way to go about these to
maximum effect.
If you are new to this you may be interested in some of these
resources.
A good, full, summary of links to guidelines
Subscribe to the relevant mailing lists (link on the left).
Craig R. McClanahan's advice how to get involved
Patches should be submitted to the developers mailing list.
Always
use diff -u to generate patches, so we can apply them using
'patch'.
Make sure the patch only contains what is intended, your
checkout could be outdated.
Make your patch from the jakarta-james directory and make sure
it conforms
to the code standards, otherwise it may be ignored. It is OK to make a
single patch covering several
files, but please only one issue at a time.
Prefix the mail subject with [PATCH]
Briefly outline the reason for your patch,
the solution your patch implements, why a patch is
needed and why your code will solve the problem. Note any bug numbers your
patch addresses.
Submit the patch as an attachment to the mail, this
mail should
preferably be in either BASE64 or QuotedPrintable format, to
prevent line wrapping.
The reason for these rules is so that commiters can easily see
what you are trying to achieve,
it is their resonsibility to manage the code and review submissions,
if you make it easy for them to see what you are doing your
patch is more likely to
be commited quickly (or at all).
Like the principles for patch submission, mark your mail [PATCH]
and ensure
your submission conforms to the code standards. Provide a Brief outline
of
your intentions, as above, so that your code can be reviewed easily, and
a
note of any relevant bug numbers.
New files must contain a reference to the Apache licence, copy
the header from an existing file.
It also helps if you send your files in an archive (tar, zip)
which preserves directories, make it from the jakarta-james
directory so we can un-tar your files into the right place.
Many improvements come as a direct result of bug
reports, and contributed fixes, often by the same person. It is sometimes
said that Apache
projects evolve because users become so fed-up waiting for bugs to be
addressed that they
fix them themselves. :)
If you report a bug,
here
we'd appreciate it if you could send a mail to the users or
developers
mailing lists, so that we can discuss it with you, bugzilla isn't a great
way for mediating
communication.
If you want to fix a bug, please contribute your changes
according to the guidelines above,
in the Code Patches section. It is much simpler to deal with
submissions if they all come
through the same channel. If you still really want to attach patches to bug
submissions, please do send us a mail tagged [PATCH] too, so
that we notice your patch.
While we are glad to accept contributions to documentation from anyone, in almost any format, because its much better than none, please consider these guidelines to help us to assimilate your contribution.
To edit an existing document try to edit the xml version in src/site/xdocs (check it out from GIT) and if you can, submit a patch as for Code Patches.
If you want to contribute new files please try to use the simple xml format we use.
If this means nothing to you please try to contribute HTML or plain text documents without any styling, so that we can get at the words and easily convert them into our XML format.
If all this seems like unnecessary nonsense, send us whatever you like, we'd still be happy to receive good documentation.
Each of the Apache James projects has its own documentation maintained with the automated build. Once a build is done, the documentation can be further committed in the site module which will be automatically published via svnpubsub to Apache James web site .
Further to this documentation, the Apache James wiki is available to any and is useful to share any useful documentation. .
Submissions to the James project must follow the coding conventions outlined in this document. James developers are asked to follow coding conventions already present in the code. (For example, if the existing code has the bracket on the same line as the if statement, then all subsequent code should also follow that convention.) Anything not explicitly mentioned in this document should adhere to the official Sun Java Coding Conventions .
Developers who commit code that does not follow the coding conventions outlined in this document will be responsible for fixing their own code.
1. Spaces between parentheses are optional. The preference is to exclude extra spaces. Both of these conventions are acceptable:
if (foo)
or
if ( foo )
2. Four spaces. NO tabs . Period. The James mailing list receives commit messages that are almost impossible to read if tabs are used.
In Emacs-speak, this translates to the following command: (setq-default tab-width 4 indent-tabs-mode nil)
3. Use Unix linefeeds for all .java source code files. Only platform-specific files (e.g. .bat files for Windows) should contain non-Unix linefeeds.
4. Javadoc must exist on all methods. Contributing a missing javadoc for any method, class, variable, etc., will be GREATLY appreciated as this will help to improve the James project.
5. The standard Apache boilerplace MUST be placed at the top of every file.
6. pom.xml files shall follow the same ordering as seen in the reference of the Maven Model , split multiple attributes each on a new line.
Eclipse IDE
Eclipse users can import those two files to enfore the code
formating :
formatting.xml
and
codetemplates.xml
.