<?xml version="1.0"?>
<!--
  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.    
-->
<document>
   <properties>
      <title>Contributors How To</title>
      <author email="danny@thought.co.uk">Danny Angus</author>
   </properties>
   <body>
       <section name="Introduction">
       <p>
           <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>
           If you are new to this you may be interested in some of these resources.<br/>
           <a href="http://jakarta.apache.org/site/guides.html">A good, full, summary of links to guidelines</a><br/>
           Subscribe to the relevant mailing lists (link on the left).<br/>
           <a href="http://jakarta.apache.org/site/contributing.html">Craig R. McClanahan's advice how to get involved</a><br/>
           <a href="http://jakarta.apache.org/site/guidelines.html">How Jakarta projects run</a><br/>
       </p>
       
       </section>

        <section name="Code Patches">
        <p>
            Patches should be submitted to the developers mailing list.<br/>
            <b>Always</b> use diff -u to generate patches, so we can apply them using 'patch'.<br/>
        Make sure you are patching the latest cvs (the HEAD).
        (You might want to try 'cvs diff -u -w -b -rHEAD' against the checked out module where
        you have implemented the patch.<br/>
            <br/>Make sure the patch only contains what is intended, your checkout could be outdated.<br/>
            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.<br/>
            Prefix the mail subject with [PATCH]<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/>
            Submit the patch as an attachment to the mail, this
        mail should preferably be in either BASE64 or QuotedPrintable format, to prevent line wrapping.<br/>
            </p>

        <p>
            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).<br/>
        </p>
        </section>
    
        <section name="Adding New Code">
        <p>
            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.<br/>
            New files must contain a reference to the Apache licence, copy the header from an existing file.<br/>
            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.
        </p>
        </section>
    
        <section name="Reporting and Fixing Bugs">
        <p>
            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. :)<br/>
            If you report a bug, <a href="http://issues.apache.org/jira">here</a> 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.<br/>
            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.
        </p>
        </section>
    
        <section name="Documentation">
        <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.<br/>
            To edit an existing document try to edit the xml version in src/xdocs (check it out from cvs) 
            and if you can, submit a patch as for Code Patches.<br/>
            If you want to contribute new files please try to use the simple xml format we use.<br/>
            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.<br/>
            If all this seems like unnecessary nonsense, send us whatever you like, we'd still be
             happy to receive good documentation.
         </p>
         </section>
    
        </body>
   </document>
