Introduction

James is a project that lives from the contributions of its community.
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.

To keep you informed on James issues, subscribe to the relevant mailing lists

Be involved in the community

An easy start is to be involved in the community.
Share your experiences with James, your needs, your enhancements proposition via the mailing lists, on gitter, or on our Bug Tracker.
Don't hesitate to write articles and blog posts. Use your preferred media to spread the love!

Reporting Bugs

Many improvements come as a direct result of bug reports.
To report a bug, please use the appropriate Bug Tracker JIRA link according to the project you want to address:
Server
Mailet
Mailbox
Protocols
MPT
Mime4j
jSieve
jSPF
jDKIM
Once you are logged on the appropriate JIRA page, click on the red Create button, then complete the different fields as accurately as possible, so that any user can reproduce the reported bug. Also note that all your information must be readable (use markdown).
Then, you have to click on Create to submit your bug.

Reporting security vulnerabilities

Security: Vulnerabilities should be announced to the Apache Security team.
PMCs will be notified about them, and will work hard to propose fixes as fast as possible.
Specific details about security in James can be found here.

Documentation

Documentation is an easy way to get on board! Check out the ~documentation label on JIRA to get some ideas.
Report on JIRA the typo you spots, the information you miss, and any improvement you can think to.
The next step is to contribute the documentation changes via Git.

To edit an existing document try to edit the xml version in src/site/xdoc (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 markdown format as shown in src/site/markdown.

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 the right 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 gitpubsub 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.

Idea or design proposals

People can submit ideas, features or design changes proposals by discussing it through the mailing lists.

Structuring design changes are tracked by ADRs (Architecture Decision Records). A discussion on the mailing list getting a consensus of the community can be the object of the writing of an ADR to confirm the change agreed upon. The Project Member Committee will take care of maintaining such records but anyone should feel free to help on such a task by proposing ADRs related to his work.

ADRs MUST be submitted under the folder `src/adr` via a pull request. The standards used for writing an ADR are described in the first ADR written for the Apache James project.

The number of the ADR should be incremental. If another ADR gets merged concurrently, the committer is responsible for updating its number accordingly.

When the ADR reaches a consensus within the community and is accepted, it can be merged and goes into effect.

An ADR can't be removed after being accepted and merged. However, a new ADR can supersede a previous one. This is so we are able to keep track on all the decisions being made regarding the project.

How to contribute to some code?

We encourage discussions prior code contributions on the mailing lists. For significant design changes the writing of ADRs is encouraged.

Your code contribution MUST be backed by a JIRA ticket.

Clone the source code of the project from its apache git repository or its GitHub
Create your branch and name it with the JIRA ticket number.
Create a Pull Request with your branch name and prefix its different commits with the same name.

Alternatively you can create a patch as outlined below, and attach it to the JIRA ticket.

A valid commit comment might be:

JAMES-2285 My awesome commit title

Here is some more details about what my commit does, and the rationals of the choice I took.

Contribution proposals

We reference some easy tasks to start with : ~newbie
We have a collection of minor fixes awaiting contributions: ~easyfix
Challenge yourself with some cool features we thought to: ~feature
Additional ideas are more than welcome. Don't hesitate to discuss that with us!

Coding Standards

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.

Submissions to the James project must follow the coding conventions outlined in the checkstyle document, which runs upon mvn compile and all phases which depend on compile. Not respecting it will halt the build, and means your contribution would not be acceptable.

Developers who commit code that does not follow the coding conventions outlined in this document will be responsible for fixing their own code.

1. 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)

2. Use Unix linefeeds for all .java source code files. Only platform-specific files (e.g. .bat files for Windows) should contain non-Unix linefeeds.

3. Javadoc MUST exist on all API methods. Contributing a missing javadoc for any method, class, variable, etc., will be GREATLY appreciated as this will help to improve the James project.

4. The standard Apache license header MUST be placed at the top of every file.

5. Your change set MUST be covered by tests. We also strongly appreciate integration tests.

6. pom.xml
We also require the following best practice regarding maven:

  • Define your dependency versions in james-project pom.xml. This structurally ensures all projects get the same version, and that there is no version clashes.
  • Don't use org.apache.james groupId for your dependencies. Use ${james.groupId}. If not, you break the policies for automatic sorting, as well as make it more ambiguous.
  • You should be ordering your dependencies. The sort order is:
        If the project is part of org.james.apache groupId? Internal dependencies goes first.
        Then we order by groupId
        Then we order by artifactId
        Then we order by type. test-jar goes last.
    Proper ordering is enforced by the project build. The build will fail in case violations are detected
  • POM files, as well as sections ordering should follows the Maven Model
You can quickly check the status of your pom files using: 
          mvn validate
You can ask the build to reorder pom files according to the rules using the sortPom profile: 
          mvn validate -PsortPom

Make sure you properly review all changes made by the automatic rewriting as XML processing tools are liberal with whitespace.

You should also 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 .

Code Patches

While we definitely prefer receiving contributions under the form of GitHub pull requests, in order to still be vendor neutral on the contribution process, we do accept submission of patches, in a process described below.

Patches should be attached to the corresponding JIRA issue.
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 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.
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.

The reason for these rules is so that committers can easily see what you are trying to achieve, it is their responsibility 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 committed quickly.