| <!DOCTYPE html> |
| <html lang="en"> |
| <head> |
| <meta charset="utf-8"> |
| <meta name="viewport" content="width=device-width,initial-scale=1"> |
| <title>Contributing :: Apache James</title> |
| <meta name="generator" content="Antora 2.3.4"> |
| <link rel="stylesheet" href="../../../_/css/site.css"> |
| </head> |
| <body class="article"> |
| <header class="header"> |
| <nav class="navbar"> |
| <div class="navbar-brand"> |
| <a class="navbar-item" href="https://james.apache.org"><img src="/_/img/james.svg" alt="james logo"> Apache James</a> |
| <button class="navbar-burger" data-target="topbar-nav"> |
| <span></span> |
| <span></span> |
| <span></span> |
| </button> |
| </div> |
| <div id="topbar-nav" class="navbar-menu"> |
| <div class="navbar-end"> |
| <a class="navbar-item" href="#">Home</a> |
| <div class="navbar-item has-dropdown is-hoverable"> |
| <a class="navbar-link" href="#">Products</a> |
| <div class="navbar-dropdown"> |
| <div class="navbar-item"><strong>James server</strong></div> |
| <a class="navbar-item" href="https://github.com/apache/james-project">Repository</a> |
| <a class="navbar-item" href="https://issues.apache.org/jira/projects/JAMES/issues">Issue Tracker</a> |
| <hr class="navbar-divider"> |
| <a class="navbar-item" href="https://james.apache.org/mime4j/index.html">Mime4J</a> |
| <a class="navbar-item" href="https://james.apache.org/jsieve/index.html">jSieve</a> |
| <a class="navbar-item" href="https://james.apache.org/jspf/index.html">jSPF</a> |
| <a class="navbar-item" href="https://james.apache.org/jdkim/index.html">jDKIM</a> |
| <a class="navbar-item" href="https://james.apache.org/hupa/index.html">HUPA</a> |
| </div> |
| </div> |
| <div class="navbar-item has-dropdown is-hoverable"> |
| <a class="navbar-link" href="#">Community</a> |
| <div class="navbar-dropdown"> |
| <!-- Not ideal but dropping the version in the href requires tweaking james-projet docs module first --> |
| <a class="navbar-item" href="/james-project/3.6.0/community/mailing-lists.html">Mailing lists</a> |
| <a class="navbar-item" href="https://gitter.im/apache/james-project"><svg version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" viewBox="0 0 32 32" class="logo-gitter-sign" data-v-44ebcb1a=""><rect x="15" y="5" width="2" height="10"></rect> <rect x="10" y="5" width="2" height="20"></rect> <rect x="5" y="5" width="2" height="20"></rect> <rect width="2" height="15"></rect></svg> Gitter</a> |
| <a class="navbar-item" href="https://twitter.com/ApacheJames"> |
| <span class="icon"> |
| <svg aria-hidden="true" data-icon="twitter" role="img" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"> |
| <path fill="#57aaee" d="M459.37 151.716c.325 4.548.325 9.097.325 13.645 0 138.72-105.583 298.558-298.558 298.558-59.452 0-114.68-17.219-161.137-47.106 8.447.974 16.568 1.299 25.34 1.299 49.055 0 94.213-16.568 130.274-44.832-46.132-.975-84.792-31.188-98.112-72.772 6.498.974 12.995 1.624 19.818 1.624 9.421 0 18.843-1.3 27.614-3.573-48.081-9.747-84.143-51.98-84.143-102.985v-1.299c13.969 7.797 30.214 12.67 47.431 13.319-28.264-18.843-46.781-51.005-46.781-87.391 0-19.492 5.197-37.36 14.294-52.954 51.655 63.675 129.3 105.258 216.365 109.807-1.624-7.797-2.599-15.918-2.599-24.04 0-57.828 46.782-104.934 104.934-104.934 30.213 0 57.502 12.67 76.67 33.137 23.715-4.548 46.456-13.32 66.599-25.34-7.798 24.366-24.366 44.833-46.132 57.827 21.117-2.273 41.584-8.122 60.426-16.243-14.292 20.791-32.161 39.308-52.628 54.253z"></path> |
| </svg> |
| </span> Twitter |
| </a> |
| <a class="navbar-item" href="#"> <svg class="octicon octicon-mark-github v-align-middle" viewBox="0 0 16 16" version="1.1" aria-hidden="true"><path fill-rule="evenodd" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"></path></svg> Github</a> |
| </div> |
| </div> |
| <!-- <div class="navbar-item"> |
| <span class="control"> |
| <a class="button is-primary" href="#">Download</a> |
| </span> |
| </div> --> |
| </div> |
| </div> |
| </nav> |
| </header> |
| <div class="body"> |
| <div class="nav-container" data-component="james-project" data-version="3.8.1"> |
| <aside class="nav"> |
| <div class="panels"> |
| <div class="nav-panel-menu is-active" data-panel="menu"> |
| <nav class="nav-menu"> |
| <button class="nav-menu-toggle" aria-label="Toggle expand/collapse all" style="display: none"></button> |
| <h3 class="title"><a href="../index.html">Apache James Server</a></h3> |
| <ul class="nav-list"> |
| <li class="nav-item" data-depth="0"> |
| <ul class="nav-list"> |
| <li class="nav-item" data-depth="1"> |
| <button class="nav-item-toggle"></button> |
| <a class="nav-link" href="../concepts/index.html">Concepts</a> |
| <ul class="nav-list"> |
| <li class="nav-item" data-depth="2"> |
| <a class="nav-link" href="../concepts/user/index.html">User Model</a> |
| </li> |
| <li class="nav-item" data-depth="2"> |
| <button class="nav-item-toggle"></button> |
| <a class="nav-link" href="../concepts/mail/index.html">Emails</a> |
| <ul class="nav-list"> |
| <li class="nav-item" data-depth="3"> |
| <button class="nav-item-toggle"></button> |
| <a class="nav-link" href="../concepts/messages/index.html">Messages</a> |
| <ul class="nav-list"> |
| <li class="nav-item" data-depth="4"> |
| <a class="nav-link" href="../concepts/messages/imf.html">IMF</a> |
| </li> |
| <li class="nav-item" data-depth="4"> |
| <a class="nav-link" href="../concepts/messages/mime.html">MIME</a> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| <li class="nav-item" data-depth="2"> |
| <button class="nav-item-toggle"></button> |
| <a class="nav-link" href="../concepts/protocols/index.html">Protocols</a> |
| <ul class="nav-list"> |
| <li class="nav-item" data-depth="3"> |
| <a class="nav-link" href="../concepts/protocols/smtp.html">SMTP</a> |
| </li> |
| <li class="nav-item" data-depth="3"> |
| <a class="nav-link" href="../concepts/protocols/pop.html">POP</a> |
| </li> |
| <li class="nav-item" data-depth="3"> |
| <a class="nav-link" href="../concepts/protocols/imap.html">IMAP</a> |
| </li> |
| <li class="nav-item" data-depth="3"> |
| <a class="nav-link" href="../concepts/protocols/jmap.html">JMAP</a> |
| </li> |
| <li class="nav-item" data-depth="3"> |
| <a class="nav-link" href="../concepts/protocols/esmtp.html">ESMTP</a> |
| </li> |
| <li class="nav-item" data-depth="3"> |
| <a class="nav-link" href="../concepts/protocols/lmtp.html">LMTP</a> |
| </li> |
| </ul> |
| </li> |
| <li class="nav-item" data-depth="2"> |
| <button class="nav-item-toggle"></button> |
| <a class="nav-link" href="../concepts/storage/index.html">Storage</a> |
| <ul class="nav-list"> |
| <li class="nav-item" data-depth="3"> |
| <a class="nav-link" href="../concepts/storage/mailbox.html">Mailboxes</a> |
| </li> |
| <li class="nav-item" data-depth="3"> |
| <a class="nav-link" href="../concepts/storage/users.html">Users</a> |
| </li> |
| </ul> |
| </li> |
| <li class="nav-item" data-depth="2"> |
| <a class="nav-link" href="../concepts/processing/index.html">Processing</a> |
| </li> |
| <li class="nav-item" data-depth="2"> |
| <a class="nav-link" href="../concepts/configuration.html">Configuration</a> |
| </li> |
| <li class="nav-item" data-depth="2"> |
| <a class="nav-link" href="../concepts/glossary.html">Glossary</a> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| <li class="nav-item" data-depth="0"> |
| <ul class="nav-list"> |
| <li class="nav-item" data-depth="1"> |
| <button class="nav-item-toggle"></button> |
| <a class="nav-link" href="../servers/index.html">Servers</a> |
| <ul class="nav-list"> |
| <li class="nav-item" data-depth="2"> |
| <button class="nav-item-toggle"></button> |
| <a class="nav-link" href="../servers/demo.html">Demo</a> |
| <ul class="nav-list"> |
| <li class="nav-item" data-depth="3"> |
| <a class="nav-link" href="../servers/5-minute-demo.html">Short Demo</a> |
| </li> |
| <li class="nav-item" data-depth="3"> |
| <a class="nav-link" href="../servers/15-minute-demo.html">Long Demo</a> |
| </li> |
| </ul> |
| </li> |
| <li class="nav-item" data-depth="2"> |
| <button class="nav-item-toggle"></button> |
| <a class="nav-link" href="../servers/basic/index.html">Basic</a> |
| <ul class="nav-list"> |
| <li class="nav-item" data-depth="3"> |
| <a class="nav-link" href="../servers/basic/context.html">Context</a> |
| </li> |
| <li class="nav-item" data-depth="3"> |
| <a class="nav-link" href="../servers/basic/objectives.html">Objectives</a> |
| </li> |
| <li class="nav-item" data-depth="3"> |
| <a class="nav-link" href="../servers/basic/concepts.html">Concepts</a> |
| </li> |
| <li class="nav-item" data-depth="3"> |
| <a class="nav-link" href="../servers/basic/architecture.html">Architecture</a> |
| </li> |
| <li class="nav-item" data-depth="3"> |
| <a class="nav-link" href="../servers/basic/conf/index.html">Configuration</a> |
| </li> |
| <li class="nav-item" data-depth="3"> |
| <a class="nav-link" href="../servers/basic/help.html">Help</a> |
| </li> |
| </ul> |
| </li> |
| <li class="nav-item" data-depth="2"> |
| <a class="nav-link" href="../servers/extendable.html">Extendable</a> |
| </li> |
| <li class="nav-item" data-depth="2"> |
| <a class="nav-link" href="../servers/test.html">Test</a> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| <li class="nav-item" data-depth="0"> |
| <ul class="nav-list"> |
| <li class="nav-item" data-depth="1"> |
| <a class="nav-link" href="../customization/index.html">Customization</a> |
| </li> |
| </ul> |
| </li> |
| <li class="nav-item" data-depth="0"> |
| <ul class="nav-list"> |
| <li class="nav-item" data-depth="1"> |
| <button class="nav-item-toggle"></button> |
| <a class="nav-link" href="../development/index.html">Developer Guide</a> |
| <ul class="nav-list"> |
| <li class="nav-item" data-depth="2"> |
| <a class="nav-link" href="../development/logging.html">Logging in Apache James</a> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| <li class="nav-item" data-depth="0"> |
| <ul class="nav-list"> |
| <li class="nav-item" data-depth="1"> |
| <button class="nav-item-toggle"></button> |
| <a class="nav-link" href="index.html">Community</a> |
| <ul class="nav-list"> |
| <li class="nav-item" data-depth="2"> |
| <a class="nav-link" href="mailing-lists.html">Mailing lists</a> |
| </li> |
| <li class="nav-item is-current-page" data-depth="2"> |
| <a class="nav-link" href="contributing.html">Contributing</a> |
| </li> |
| <li class="nav-item" data-depth="2"> |
| <a class="nav-link" href="guidelines.html">Guidelines</a> |
| </li> |
| <li class="nav-item" data-depth="2"> |
| <a class="nav-link" href="download.html">Download releases</a> |
| </li> |
| <li class="nav-item" data-depth="2"> |
| <a class="nav-link" href="website.html">Building and publishing the website</a> |
| </li> |
| <li class="nav-item" data-depth="2"> |
| <a class="nav-link" href="release.html">Creating an official Apache James release</a> |
| </li> |
| <li class="nav-item" data-depth="2"> |
| <a class="nav-link" href="support.html">Professional support</a> |
| </li> |
| <li class="nav-item" data-depth="2"> |
| <button class="nav-item-toggle"></button> |
| <span class="nav-text">Apache Software Foundation</span> |
| <ul class="nav-list"> |
| <li class="nav-item" data-depth="3"> |
| <a class="nav-link" href="https://www.apache.org/">ASF</a> |
| </li> |
| <li class="nav-item" data-depth="3"> |
| <a class="nav-link" href="https://www.apache.org/foundation/getinvolved.html">Get involved</a> |
| </li> |
| <li class="nav-item" data-depth="3"> |
| <a class="nav-link" href="https://www.apache.org/foundation/faq.html">FAQ</a> |
| </li> |
| <li class="nav-item" data-depth="3"> |
| <a class="nav-link" href="https://www.apache.org/licenses/">Licenses</a> |
| </li> |
| <li class="nav-item" data-depth="3"> |
| <a class="nav-link" href="https://www.apache.org/security/">Security</a> |
| </li> |
| <li class="nav-item" data-depth="3"> |
| <a class="nav-link" href="https://www.apache.org/foundation/sponsorship.html">Sponsorship</a> |
| </li> |
| <li class="nav-item" data-depth="3"> |
| <a class="nav-link" href="https://www.apache.org/foundation/thanks.html">Thanks</a> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| </nav> |
| </div> |
| <div class="nav-panel-explore" data-panel="explore"> |
| <div class="context"> |
| <span class="title">Apache James Server</span> |
| <span class="version">3.8.1 SNAPSHOT</span> |
| </div> |
| <ul class="components"> |
| <li class="component is-current"> |
| <div class="title"><a href="../index.html">Apache James Server</a></div> |
| <ul class="versions"> |
| <li class="version is-current is-latest"> |
| <a href="../index.html">3.8.1 SNAPSHOT</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component"> |
| <div class="title"><a href="../../../james-site/latest/index.html">Apache James Site</a></div> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../../james-site/latest/index.html">latest</a> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </aside> |
| </div> |
| <main class="article"> |
| <div class="toolbar" role="navigation"> |
| <button class="nav-toggle"></button> |
| <a href="../../../james-site/latest/homepage.html" class="home-link"></a> |
| <nav class="breadcrumbs" aria-label="breadcrumbs"> |
| <ul> |
| <li><a href="../index.html">Apache James Server</a></li> |
| <li><a href="index.html">Community</a></li> |
| <li><a href="contributing.html">Contributing</a></li> |
| </ul> |
| </nav> |
| <div class="edit-this-page"><a href="https://github.com/apache/james-project/blob/master/docs/modules/community/pages/contributing.adoc">Edit this Page</a></div> |
| </div> |
| <div class="content"> |
| <aside class="toc sidebar" data-title="Contents" data-levels="2"> |
| <div class="toc-menu"></div> |
| </aside> |
| <article class="doc"> |
| <h1 class="page">Contributing</h1> |
| <div id="preamble"> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>This document defines the different ways available for contributing to the Apache James project.</p> |
| </div> |
| <div class="paragraph"> |
| <p>To keep you informed on James issues, subscribe to the relevant <a href="mailing-lists.html" class="page">mailing lists</a>.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="_be_involved_in_the_community"><a class="anchor" href="#_be_involved_in_the_community"></a>Be involved in the community</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>An easy start is to be involved in the community.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Share your experiences with James, your needs, your enhancements proposition via the |
| <a href="mailing-lists.html" class="page">mailing lists</a>, on <a href="https://gitter.im/apache/james-project">Gitter</a>, or on our |
| <a href="https://issues.apache.org/jira/projects/JAMES/issues">Bug Tracker</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Don’t hesitate to write articles and blog posts. Use your preferred media to spread the love!</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="_reporting_bugs"><a class="anchor" href="#_reporting_bugs"></a>Reporting bugs</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>Many improvements come as a direct result of bug reports.</p> |
| </div> |
| <div class="paragraph"> |
| <p>To report a bug, please use the appropriate Bug Tracker JIRA link according to the project you want to address:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="https://issues.apache.org/jira/browse/JAMES">Server</a></p> |
| </li> |
| <li> |
| <p><a href="https://issues.apache.org/jira/browse/MAILET">Mailet</a></p> |
| </li> |
| <li> |
| <p><a href="https://issues.apache.org/jira/browse/MAILBOX">Mailbox</a></p> |
| </li> |
| <li> |
| <p><a href="https://issues.apache.org/jira/browse/PROTOCOLS">Protocols</a></p> |
| </li> |
| <li> |
| <p><a href="https://issues.apache.org/jira/browse/MPT">MPT</a></p> |
| </li> |
| <li> |
| <p><a href="https://issues.apache.org/jira/browse/MIME4J">Mime4j</a></p> |
| </li> |
| <li> |
| <p><a href="https://issues.apache.org/jira/browse/JSIEVE">jSieve</a></p> |
| </li> |
| <li> |
| <p><a href="https://issues.apache.org/jira/browse/JSPF">jSPF</a></p> |
| </li> |
| <li> |
| <p><a href="https://issues.apache.org/jira/browse/JDKIM">jDKIM</a></p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>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).</p> |
| </div> |
| <div class="paragraph"> |
| <p>Then, you have to click on Create to submit your bug.</p> |
| </div> |
| <div class="sect2"> |
| <h3 id="_reporting_security_vulnerabilities"><a class="anchor" href="#_reporting_security_vulnerabilities"></a>Reporting security vulnerabilities</h3> |
| <div class="paragraph"> |
| <p><a href="http://www.apache.org/security/">Security vulnerabilities</a> 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.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Specific details about security in James can be found here.</p> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="_documentation"><a class="anchor" href="#_documentation"></a>Documentation</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>Documentation is an easy way to get on board! Check out the |
| <a 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. |
| Report on JIRA the typos you spot, the information you miss, and any improvement you can think of. |
| The next step is to contribute the documentation changes via <a href="https://github.com/apache/james-project/tree/master/docs/modules">Git</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>To edit an existing document try to edit the adoc version in <code>docs/modules</code> (check it out from Git) and if you can, submit a |
| patch as for <a href="#_code_patches">Code Patches</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If you want to contribute new files please try to use the AsciiDoc format as shown in <code>docs/modules</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If all this seems like unnecessary nonsense, send us whatever you like, we’d still be happy to receive good documentation.</p> |
| </div> |
| <div class="paragraph"> |
| <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 href="https://git-wip-us.apache.org/repos/asf/james-site.git">site module</a> |
| which will be automatically published via gitpubsub to <a href="http://james.apache.org">Apache James web site</a>.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="_idea_or_design_proposals"><a class="anchor" href="#_idea_or_design_proposals"></a>Idea or design proposals</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>People can submit ideas, features or design changes proposals by discussing it through the |
| <a href="mailing-lists.html" class="page">mailing lists</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Structuring design changes are tracked by <a href="https://github.com/joelparkerhenderson/architecture-decision-record">ADRs</a> |
| (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.</p> |
| </div> |
| <div class="paragraph"> |
| <p>ADRs <strong>MUST</strong> be submitted under the folder <code>src/adr</code> via a pull request. The standards used for writing an ADR are |
| described in the <a href="https://github.com/apache/james-project/blob/master/src/adr/0001-record-architecture-decisions.md">first ADR</a> |
| written for the Apache James project.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The number of the ADR should be incremental. If another ADR gets merged concurrently, the committer is responsible for |
| updating its number accordingly.</p> |
| </div> |
| <div class="paragraph"> |
| <p>When the ADR reaches a consensus within the community and is accepted, it can be merged and goes into effect.</p> |
| </div> |
| <div class="paragraph"> |
| <p>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.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="_how_to_contribute_some_code"><a class="anchor" href="#_how_to_contribute_some_code"></a>How to contribute some code?</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>We encourage discussions prior code contributions on the <a href="mailing-lists.html" class="page">mailing lists</a>. For significant design |
| changes the writing of <a href="#_idea_or_design_proposals">ADRs</a> is encouraged.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Your code contribution <strong>must</strong> be backed by a <a href="#_reporting_bugs">JIRA ticket</a>.</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Clone the source code of the project from its <a href="git://git.apache.org/james-project.git">apache git repository</a> or its |
| <a href="https://github.com/apache/james-project">GitHub</a></p> |
| </li> |
| <li> |
| <p>Create your branch and name it with the JIRA ticket number.</p> |
| </li> |
| <li> |
| <p>Create a Pull Request on GitHub with your branch name and prefix its different commits with the same name.</p> |
| </li> |
| <li> |
| <p>A build will be started for your work on the <a href="https://ci-builds.apache.org/job/james/job/ApacheJames/">Apache CI</a>.</p> |
| </li> |
| <li> |
| <p>Active contributors will review your work, and merge it.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>A valid commit comment might be:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code>JAMES-2285 My awesome commit title |
| |
| Here is some more details about what my commit does, and the rationals of the choice I took.</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Alternatively you can create a patch as <a href="#_code_patches">outlined below</a>, and attach it to the JIRA ticket.</p> |
| </div> |
| <div class="sect2"> |
| <h3 id="_licenses"><a class="anchor" href="#_licenses"></a>Licenses</h3> |
| <div class="paragraph"> |
| <p>All contributions to the James project are made under the <a href="https://www.apache.org/licenses">Apache license 2.0</a></p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_contributions_proposals"><a class="anchor" href="#_contributions_proposals"></a>Contributions proposals</h3> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>We reference some easy tasks to start with: |
| <a 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></p> |
| </li> |
| <li> |
| <p>We have a collection of minor fixes awaiting contributions: |
| <a 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></p> |
| </li> |
| <li> |
| <p>Challenge yourself with some cool features we thought to: |
| <a 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></p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Additional ideas are more than welcome. Don’t hesitate to discuss that with us!</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_coding_standards"><a class="anchor" href="#_coding_standards"></a>Coding standards</h3> |
| <div class="paragraph"> |
| <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> |
| </div> |
| <div class="paragraph"> |
| <p>Submissions to the James project must follow the coding conventions outlined in the |
| <a href="https://github.com/apache/james-project/blob/master/checkstyle.xml">checkstyle document</a>, which runs |
| upon <code>mvn compile</code> and all phases which depend on <code>compile</code>. Not respecting it will halt the build, and means |
| your contribution would not be |
| acceptable.</p> |
| </div> |
| <div class="paragraph"> |
| <p><strong>Developers who commit code that does not follow the coding conventions outlined in this document will be responsible |
| for fixing their own code.</strong> `.</p> |
| </div> |
| <div class="olist arabic"> |
| <ol class="arabic" start="3"> |
| <li> |
| <p>Four spaces. <strong>No tabs.</strong> Period. |
| The James mailing list receives commit messages that are almost impossible to read if tabs are used.</p> |
| </li> |
| <li> |
| <p>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> |
| </li> |
| <li> |
| <p>Javadoc <strong>MUST</strong> 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> |
| </li> |
| <li> |
| <p>The standard Apache license header <strong>MUST</strong> be placed at the top of every file.</p> |
| </li> |
| <li> |
| <p>Your change set <strong>MUST</strong> be covered by tests. We also strongly appreciate integration tests.</p> |
| </li> |
| <li> |
| <p>We also require the following best practice regarding maven and the <strong>pom.xml</strong>:</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>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.</p> |
| </li> |
| <li> |
| <p>Don’t use <em>org.apache.james</em> groupId for internal dependencies. Use <em>${james.groupId}</em>. If not, you break the policies |
| for automatic sorting, as well as make it more ambiguous. One exception is apache-mime4j-* artifacts which share the |
| james groupId despite living in a different repository.</p> |
| </li> |
| <li> |
| <p>You should be ordering your dependencies. The sort order of tags and dependencies in the pom is automatically enforced at build time. By default the build |
| will fail if violations are detected.</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| </ol> |
| </div> |
| <div class="paragraph"> |
| <p>The pom file ordering can be quickly checked using :</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code>mvn validate</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>If you get an error and want the tool to fix it for you, you can use :</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code>mvn validate -PsortPom</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The <code>sortPom</code> profile can be used on all maven phases. Make sure to review the changes made by the tool, it is known to |
| sometimes remove whitespaces which may not be desirable.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_code_patches"><a class="anchor" href="#_code_patches"></a>Code patches</h3> |
| <div class="paragraph"> |
| <p>While we definitely prefer receiving contributions under the form of <a href="#_how_to_contribute_some_code">GitHub pull requests</a>, |
| in order to still be vendor neutral on the contribution process, we do accept submission of patches, in a process described |
| below.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Patches should be attached to the corresponding JIRA issue.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Always use diff -u to generate patches, so we can apply them using 'patch'.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Make sure the patch only contains what is intended, your checkout could be outdated.</p> |
| </div> |
| <div class="paragraph"> |
| <p>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.</p> |
| </div> |
| <div class="paragraph"> |
| <p>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.</p> |
| </div> |
| <div class="paragraph"> |
| <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.</p> |
| </div> |
| </div> |
| </div> |
| </div> |
| </article> |
| </div> |
| </main> |
| </div> |
| <footer class="footer"> |
| <p>This page was built using the Antora default UI.</p> |
| <p>The source code for this UI is licensed under the terms of the MPL-2.0 license.</p> |
| </footer> |
| <script id="site-script" src="../../../_/js/site.js" data-ui-root-path="../../../_"></script> |
| <script async src="../../../_/js/vendor/highlight.js"></script> |
| </body> |
| </html> |
