blob: 1bf52fab9e4324802314d9c811cab9894f143e3e [file] [log] [blame]
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
-->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<!-- Generated by Apache Maven Doxia at 2021-11-12 -->
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>Apache James Project &#x2013; Contributors How To</title>
<style type="text/css" media="all">
@import url("./css/james.css");
@import url("./css/maven-base.css");
@import url("./css/maven-theme.css");
@import url("./css/site.css");
@import url("./js/jquery/css/custom-theme/jquery-ui-1.8.5.custom.css");
@import url("./js/jquery/css/print.css");
@import url("./js/fancybox/jquery.fancybox-1.3.4.css");
</style>
<script type="text/javascript" src="./js/jquery/js/jquery-1.4.2.min.js"></script>
<script type="text/javascript" src="./js/jquery/js/jquery-ui-1.8.5.custom.min.js"></script>
<script type="text/javascript" src="./js/fancybox/jquery.fancybox-1.3.4.js"></script>
<link rel="stylesheet" href="./css/print.css" type="text/css" media="print" />
<meta name="author" content="James Project Web Team" />
<meta name="Date-Revision-yyyymmdd" content="20211112" />
<meta http-equiv="Content-Language" content="en" />
<!-- Google Analytics -->
<script type="text/javascript">
var _gaq = _gaq || [];
_gaq.push(['_setAccount', 'UA-1384591-1']);
_gaq.push(['_trackPageview']);
(function() {
var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
var s = document.getElementsByTagName('script').item(0); s.parentNode.insertBefore(ga, s);
})();
</script>
</head>
<body class="composite">
<div id="banner">
<a href="index.html" id="bannerLeft" title="james-logo.png">
<img src="images/logos/james-logo.png" alt="James Project" />
</a>
<a href="https://www.apache.org/index.html" id="bannerRight">
<img src="images/logos/asf_logo_small.png" alt="The Apache Software Foundation" />
</a>
<div class="clear">
<hr/>
</div>
</div>
<div id="breadcrumbs">
<div class="xleft">
<span id="publishDate">Last Published: 2021-11-12</span>
</div>
<div class="xright"> <a href="index.html" title="Home">Home</a>
|
<a href="documentation.html" title="James">James</a>
|
<a href="mime4j/index.html" title="Mime4J">Mime4J</a>
|
<a href="jsieve/index.html" title="jSieve">jSieve</a>
|
<a href="jspf/index.html" title="jSPF">jSPF</a>
|
<a href="jdkim/index.html" title="jDKIM">jDKIM</a>
</div>
<div class="clear">
<hr/>
</div>
</div>
<div id="leftColumn">
<div id="navcolumn">
<h5>James components</h5>
<ul>
<li class="expanded">
<a href="documentation.html" title="About James">About James</a>
<ul>
<li class="none">
<a href="mail.html" title="Mailing Lists">Mailing Lists</a>
</li>
<li class="none">
<strong>Contributing</strong>
</li>
<li class="none">
<a href="guidelines.html" title="Guidelines">Guidelines</a>
</li>
<li class="none">
<a href="https://issues.apache.org/jira/browse/JAMES" title="Issue tracker">Issue tracker</a>
</li>
<li class="none">
<a href="team-list.html" title="Who We Are">Who We Are</a>
</li>
<li class="none">
<a href="license.html" title="License">License</a>
</li>
<li class="none">
<a href="thanks.html" title="Thanks">Thanks</a>
</li>
<li class="none">
<a href="support.html" title="Professional support">Professional support</a>
</li>
<li class="none">
<a href="download.cgi" title="Download releases">Download releases</a>
</li>
</ul>
</li>
<li class="collapsed">
<a href="server/index.html" title="Server">Server</a>
</li>
<li class="collapsed">
<a href="mailet/index.html" title="Mailets">Mailets</a>
</li>
<li class="collapsed">
<a href="mailbox/index.html" title="Mailbox">Mailbox</a>
</li>
<li class="collapsed">
<a href="protocols/index.html" title="Protocols">Protocols</a>
</li>
<li class="collapsed">
<a href="mpt/index.html" title="MPT">MPT</a>
</li>
</ul>
<h5>Apache Software Foundation</h5>
<ul>
<li>
<strong>
<a title="ASF" href="http://www.apache.org/">ASF</a>
</strong>
</li>
<li>
<a title="Get Involved" href="http://www.apache.org/foundation/getinvolved.html">Get Involved</a>
</li>
<li>
<a title="FAQ" href="http://www.apache.org/foundation/faq.html">FAQ</a>
</li>
<li>
<a title="License" href="http://www.apache.org/licenses/" >License</a>
</li>
<li>
<a title="Sponsorship" href="http://www.apache.org/foundation/sponsorship.html">Sponsorship</a>
</li>
<li>
<a title="Thanks" href="http://www.apache.org/foundation/thanks.html">Thanks</a>
</li>
<li>
<a title="Security" href="http://www.apache.org/security/">Security</a>
</li>
</ul>
<a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy">
<img class="poweredBy" alt="Built by Maven" src="./images/logos/maven-feather.png" />
</a>
</div>
</div>
<div id="bodyColumn">
<div id="contentBox">
<section>
<h2><a name="Introduction"></a>Introduction</h2>
<p>
James is a project that lives from the contributions of its community.<br />
<b>Anyone can contribute.</b>
<br />
That's right, we always want to hear from people with
contributions to the code,
the documentation, the website, and bug reports.
<br />
The rest of this document outlines the way to go about these to
maximum effect.
<br />
</p>
<p>
To keep you informed on James issues, subscribe to the relevant
<a class="externalLink" href="https://james.apache.org/mail.html">mailing lists</a>
<br />
</p>
</section>
<section>
<h2><a name="Be_involved_in_the_community"></a>Be involved in the community</h2>
<p>
An easy start is to be involved in the community.<br />
Share your experiences with James, your needs, your enhancements proposition via the
<a class="externalLink" href="https://james.apache.org/mail.html">mailing lists</a>, on <a class="externalLink" href="https://gitter.im/apache/james-project">
gitter</a>, or on our <a class="externalLink" href="https://issues.apache.org/jira/browse/JAMES">Bug Tracker</a>.<br />
Don't hesitate to write articles and blog posts. Use your preferred media to spread the love!
</p>
</section>
<section>
<h2><a name="Reporting_Bugs"></a>Reporting Bugs</h2>
<p>
Many improvements come as a direct result of bug reports.
<br />
To report a bug, please use the appropriate Bug Tracker JIRA link according
to the project you want to address:
<br />
<a class="externalLink" href="https://issues.apache.org/jira/browse/JAMES">Server</a>
<br />
<a class="externalLink" href="https://issues.apache.org/jira/browse/MAILET">Mailet</a>
<br />
<a class="externalLink" href="https://issues.apache.org/jira/browse/MAILBOX">Mailbox</a>
<br />
<a class="externalLink" href="https://issues.apache.org/jira/browse/PROTOCOLS">Protocols</a>
<br />
<a class="externalLink" href="https://issues.apache.org/jira/browse/MPT">MPT</a>
<br />
<a class="externalLink" href="https://issues.apache.org/jira/browse/MIME4J">Mime4j</a>
<br />
<a class="externalLink" href="https://issues.apache.org/jira/browse/JSIEVE">jSieve</a>
<br />
<a class="externalLink" href="https://issues.apache.org/jira/browse/JSPF">jSPF</a>
<br />
<a class="externalLink" href="https://issues.apache.org/jira/browse/JDKIM">jDKIM</a>
<br />
<a class="externalLink" href="https://issues.apache.org/jira/browse/HUPA">Hupa</a>
<br />
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 markedown).
<br />
Then, you have to click on Create to submit your bug.
</p>
<section>
<h3><a name="Reporting_security_vulnerabilities"></a>Reporting security vulnerabilities</h3>
<a class="comm" href="http://www.apache.org/security/">Security</a>: Vulnerabilities should be announced to the Apache Security team.<br />
PMCs will be notified about them, and will work hard to propose fixes as fast as possible.<br />
Specific details about security in James can be found <a class="comm" href="http://james.apache.org/server/feature-security.html">here</a>.
</section>
</section>
<section>
<h2><a name="Documentation"></a>Documentation</h2>
<p>Documentation is an easy way to get on board!
Check out the <a class="comm" href="https://issues.apache.org/jira/issues/?jql=project%20%3D%20JAMES%20AND%20resolution%20%3D%20Unresolved%20AND%20labels%20%3D%20documentation%20ORDER%20BY%20priority%20DESC%2C%20updated%20DESC">~documentation</a> label on JIRA to get some ideas.<br />
Report on JIRA the typo you spots, the information you miss, and any improvement you can think to.<br />
The next step is to contribute the documentation changes via <a class="comm" href="https://github.com/apache/james-project/tree/master/src/site/xdoc">Git</a>.
</p>
<p>
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.
</p>
<p>
If you want to contribute new files please try to use the markdown format as
shown in src/site/markdown.
</p>
<p>
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.
</p>
<p>
If all this seems like unnecessary nonsense, send us whatever you
like, we'd still be happy to receive good documentation.
</p>
<p>
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
<a class="externalLink" href="https://git-wip-us.apache.org/repos/asf/james-site.git">site module</a>
which will be automatically published via gitpubsub
to <a class="externalLink" href="http://james.apache.org">Apache James web site</a>.
</p>
<p>
Further to this documentation, the <a class="externalLink" href="http://wiki.apache.org/james/">Apache James wiki</a>
is available to any and is useful to share any useful documentation.
</p>
</section>
<section>
<h2><a name="How_to_contribute_to_the_code.3F"></a>How to contribute to the code?</h2>
<p>
Clone the source code of the project from its
<a class="externalLink" href="git://git.apache.org/james-project.git">apache git repository</a>
or its <a class="externalLink" href="https://github.com/apache/james-project">Github</a>
<br />
Create your branch and name it with the JIRA ticket number.<br />
Create a Pull Request with your branch name and prefix its different commits with the same name.
<br />
</p>
<p>Alternatively you can create a patch as <a href="#Code_Patches">outlined below</a>, and attach it to the JIRA ticket.</p>
<p>A valid commit comment might be:</p>
<div>
<pre>JAMES-2285 My awesome commit title
Here is some more details about what my commit does, and the rationals of the choice I took.</pre></div>
<section>
<h3><a name="Contribution_proposals"></a>Contribution proposals</h3>
<p>
We reference some easy tasks to start with :
<a class="comm" href="https://issues.apache.org/jira/issues/?jql=project%20%3D%20JAMES%20AND%20resolution%20%3D%20Unresolved%20AND%20labels%20%3D%20newbie%20ORDER%20BY%20priority%20DESC%2C%20updated%20DESC">~newbie</a>
<br /> We have a collection of minor fixes awaiting contributions:
<a class="comm" href="https://issues.apache.org/jira/issues/?jql=project%20%3D%20JAMES%20AND%20resolution%20%3D%20Unresolved%20AND%20labels%20%3D%20easyfix%20ORDER%20BY%20priority%20DESC%2C%20updated%20DESC">~easyfix</a>
<br /> Challenge yourself with some cool features we thought to:
<a class="comm" href="https://issues.apache.org/jira/issues/?jql=project%20%3D%20JAMES%20AND%20resolution%20%3D%20Unresolved%20AND%20labels%20%3D%20feature%20ORDER%20BY%20priority%20DESC%2C%20updated%20DESC">~feature</a>
<br />Additional ideas are more than welcome. Don't hesitate to discuss that with us!
</p>
</section>
</section>
<section>
<h2><a name="Coding_Standards"></a>Coding Standards</h2>
<p>
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.
</p>
<p>
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
<a class="externalLink" href="http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html">Sun
Java Coding Conventions
</a>
.
</p>
<p>
<b>Developers who commit code that does not follow
the coding conventions outlined in this document will be
responsible for fixing their own code.
</b>
</p>
<p>
1. Your code should pass our <a class="externalLink" href="https://github.com/apache/james-project/blob/master/checkstyle.xml">checkstyle</a>
which runs upon mvn clean install.
</p>
<p>
2. Extra spaces between parentheses are not allowed:
</p>
<p>
</p>
<div class="source">
<pre>
if (foo) &gt; Good
or
if ( foo ) &gt; Bad
</pre></div>
<p>
3. Four spaces.<b>NO tabs</b>. Period. <br />
The James mailing list receives commit messages that
are almost impossible to read if tabs are used.
</p>
<p>
In Emacs-speak, this translates to the following command:
(setq-default tab-width 4 indent-tabs-mode nil)
</p>
<p>
4. Use Unix linefeeds for all .java source code files. Only
platform-specific files (e.g. .bat files for Windows) should
contain non-Unix linefeeds.
</p>
<p>5. Javadoc <b>MUST</b>
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.
</p>
<p>6. The standard Apache license header <b>MUST</b> be placed at the top of every file.</p>
<p>7. Your change set <b>MUST</b> be covered by tests. We also strongly appreciate integration tests.</p>
<p>
8. <b>pom.xml</b>
<br />
We also require the following best practice regarding maven:
</p>
<ul>
<li>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.</li>
<li>Don't use <i>org.apache.james</i> groupId for your dependencies. Use <i>${james.groupId}</i>.
If not, you break the policies for automatic sorting, as well as make it more ambiguous.</li>
<li>You should be ordering your dependencies. The sort order is:
<ul>
<ol style="list-style-type: decimal">If the project is part of org.james.apache groupId? Internal dependencies goes first.</ol>
<ol style="list-style-type: decimal">Then we order by groupId</ol>
<ol style="list-style-type: decimal">Then we order by artifactId</ol>
<ol style="list-style-type: decimal">Then we order by type. <i>test-jar</i> goes last.</ol>
</ul>
Proper ordering is enforced by the project build. The build will fail in case violations are detected</li>
<li>POM files, as well as sections ordering should follows the <a class="externalLink" href="http://maven.apache.org/ref/3.0.3/maven-model/maven.html">Maven Model</a></li>
</ul>
You can quickly check the status of your pom files using:
<div>
<pre>
mvn validate
</pre></div>
You can ask the build to reorder pom files according to the rules using the sortPom profile:
<div>
<pre>
mvn validate -PsortPom
</pre></div>
<p>Make sure you properly review all changes made by the automatic rewriting as XML processing tools are liberal
with whitespace.</p>
<p>You should also split multiple attributes each on a new line.</p>
<p>
<b>Eclipse IDE</b>
<br />
Eclipse users can import those two files to enfore the code
formating :
<a href="downloads/formatting.xml">formatting.xml</a>
and
<a href="downloads/codetemplates.xml">codetemplates.xml</a>
.
</p>
</section>
<section>
<h2><a name="Code_Patches"></a>Code Patches</h2>
<p>
Patches should be attached to the corresponding JIRA issue.
<br />
<b>Always</b>
use diff -u to generate patches, so we can apply them using
'patch'.
<br />
<br />
Make sure the patch only contains what is intended, your
checkout could be outdated.
<br />
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.
<br />
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.
<br />
</p>
<p>
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.
<br />
</p>
</section>
</div>
</div>
<div class="clear">
<hr/>
</div>
<div id="footer">
<div class="xright">Copyright &#169; 2006-2021
<a href="https://www.apache.org/">The Apache Software Foundation</a>.
All Rights Reserved.
</div>
<div class="clear">
<hr/>
</div>
</div>
</body>
</html>