<?xml version="1.0" encoding="ISO-8859-1"?>
<document url="http://castor.codehaus.org/contributing.xml">

    <properties>
        <title>Contributing to Castor</title>
        <author email="werner DOT guttmann AT gmx DOT net">Werner Guttmann</author>
        <abstract>
            Outlines how to contribute to Castor.
        </abstract>
        <status>Final</status>
    </properties>
    
  <body>
  
    <title>Contributing to Castor</title>

    <section title="Introduction">

        <p>The Castor project is an Open Source project hosted at the 
           <a href="http://www.codehaus.org">Codehaus</a>, and it is released under a very 
           open license. This means there are many ways to contribute to the 
           project by e.g. coding, documenting, answering questions on the mailing lists,
           proposing ideas, reporting bugs, suggesting bug-fixes, etc.</p>

        <p>To begin with, we suggest you to subscribe to the 
           <a href="lists.html">Castor mailing lists</a>. Listen-in for a while, 
           to hear how others make contibutions.</p>

        <p>You can get your local working copy of the current code base (or any particular 
           release) from the <a href="scm.html">Castor SVN repository</a>. Review the todo list at
           <a href="http://jira.codehaus.org/browse/CASTOR">Jira</a>, choose a task 
           (or perhaps you have noticed something that needs patching). Make the changes, 
           do the testing, generate a patch (if you need then discuss it on the dev mailing 
           list), and add the patch to Jira.</p>

        <p>Document writers are usually the most wanted people, so if you like to help but 
           you're not familiar with the innermost technical details, don't worry, as all other 
           committers will sufficient spend time with you trying to assist you with 
           their knowledge.</p>
    
    </section>  

    <section title="Guidelines For Code Contribution">

        <p>All code contributions must be under the license and copyright of the
           project to which you contribute. By contributing code you agree that we
           can distribute the contribution under the terms of the license, that it
           can be distributed without any royalties, copyright, trademark, patent or
           other legal lock ups. Open source means no discrimination against any
           group or individual that may wish to use the code.</p>

        <p>When making a contribution you are granting us a world wide, royalty free,
           unlimited in time license to re-distribute the code under the Exolab and/or 
           Apache license. In case you wonder, you remain the original author and 
           copyright holder of the contribution, you just give other people a license 
           to use it as well. Thank you.</p>

        <p>It's perfectly ok to put your name and e-mail address in the code.</p>

        <p>When sending patches, unified diff files (3 lines before, 3 lines after) work best:</p>
        
<code-panel><![CDATA[
  svn diff <file>]]></code-panel>
  
        <p>against the up-to-date SVN version, or</p>
            
<code-panel><![CDATA[
  diff -u <file1> <file2>
]]></code-panel>

        <p>It is very important for sending test cases along with the patch of a
           new feature and a bug fix, as a test case will help the committers 
           to assess the validity of the problem in question and your proposed 
           solution. In general, a test case - showing a feature being added or a 
           bug being fixed - proves that the patch plays along nicely with other 
           code and does not introduce any side effects.</p>

        <p>Committer are encouraged to commit a patch only if (s)he fully 
           understands the patch. A test case that assists the committer to gain 
           a full understanding as mandated per above statement, as such ensures
           the committer understands what the patch does and as a result encourages
           a prompt review and check-in.</p>

        <p>Also, a test case is the easiest way to ensure your contribution will
           not be broken by another patch later. It becomes even more important
           if your project depends on a feature that you're contributing.</p>

        <p>The last requirement for contributing code is to create an
           <a href="http://jira.codeahus.org/browse/CASTOR">issue</a> (providing a
           full description of the issue/enhancement) and attach your patch 
           (in from of a unified diff) to this issue. Having created such an issue,
           this allows your request to be fully traceable.</p>

    </section>

    <section title="Guidelines For Committers">

        <p><i>Familiarize yourself.</i> Take some time to understand the directory
           structure, build environment, interaction between components, coding and commenting
           style. Nothing out of the ordinary, but still not all projects are identical.</p>

        <p><i>Before starting to work please advertise.</i> It's pointless to have two people
           working on the same feature. Send an e-mail to the developer mailing list and
           announce what and how. If you don't get a reply within a day, you can assume the
           coast is clear.</p>

      <p><i>Test before you commit.</i> Before committing any changes run a <tt>svn update</tt>
         to make sure you have the latest code base. Run the test cases to make sure nothing
         is broken.</p>

      <p><i>Commit all at once.</i> If the change involves more than a single file, make sure
         to commit all the changes together. A partially committed SVN tree is not a pretty
         sight. No lunch breaks, meetings or sleep during commits.</p>

      <p><i>Be ready to receive complaints.</i> Hopefully all works fine, but if changes
         to break existing code, people will complain. Be ready to answer their e-mails
         and apply the proper fixes. No going on vacation five minutes after a commit.</p>

      <p><i>Put your name so people know who to credit.</i> (Also who to blame). Initials
         work just fine, your full name and e-mail address are already on the main page.
         If you've added a new file, feel free to put your name and e-mail address as the
         author. If you're fixing a file, put your initials on the comment.</p>

      <p><i>Observe release time.</i> We're going to announce a new release five hours prior
         to making it. That gives you four hours to commit any changes, make sure nothing
         breaks. Don't leave the computer before the release is done. If you can't make
         it, there's alway the next release.</p>

      <p><i>Document what you've done.</i> In-code documentation, SVN commit messages,
         and the changelog. Major changes should always be recorded in the changelog.</p>

      <p><i>Use the document DTD.</i> When adding new documentation use the document DTD.
         Specify the proper document URL, properties, body and section. Everything
         inside the body/header/section is XHTML. That means well formed HTML.
         If it's not, you won't be able to build the docs.</p>

            <p>We don't have a particular style for documentation, and we do appreciate
               a sense of humor, sarcasm and literary expression. Just don't overdue it,
               and please, no cliche.</p>

        </section>

        <section title="Licensing Policy">

            <p>We have a simple policy regarding distributable code. Either it's open source
               and compatible in license, or it's an API that is freely distributable.</p>

      <p>BSD-like and MPL-like licenses are compatible and can be mixed in the
         same code base. Liberal licenses and public domain are also fine.</p>

      <p>APIs need not be open source, but they must be freely distributable.
         As a policy we like to stick with standard APIs and never modify them,
         so the license has little affect. We do favor public domains APIs like
         SAX over tightly controlled APIs, and hopefully we can all do something
         about that.</p>

      <p>Pay special attention to pre-release availability and trademark issues.
         Several committees and companies require proper trademark acknowledgement in
         the documentation. Some of them are available for distribution only
         once they have been formally released. This policy applies to all APIs
         coming from Sun.</p>

        </section>
    
    <section title="Building Castor">
   
        <section title="Introduction">

         <p>Castor uses Ant as the build environment. To build Castor from the
            source run <tt>bin/build.sh</tt> or <tt>bin\build.bat</tt> in the Castor root
            directory with one (or any) of the following targets:</p>

         <ctable cellpadding="4" border="1">
           <crow><td>targets</td><td>Lists the build targets</td></crow>
           <crow><td>clean</td><td>Cleans the build and distribution directories</td></crow>
           <crow><td>all</td><td>Cleans and builds all the packages and examples</td></crow>
           <crow><td>release</td><td>Cleans and builds all the release packages
                                  (JAR, source, doc, tarball) in the dist directory</td></crow>
           <crow><td>main</td><td>Builds the main packages (including debugging info)</td></crow>
           <crow><td>examples</td><td>Builds the example packages (including debugging info)</td></crow>
           <crow><td>tests</td><td>Builds the test packages (including debugging info)</td></crow>
           <crow><td>jar</td><td>Builds the binary JAR in the dist directory</td></crow>
           <crow><td>doc</td><td>Builds the documentation</td></crow>
           <crow><td>api</td><td>Builds the API JavaDocs</td></crow>
           <crow><td>javadoc</td><td>Builds the full JavaDocs</td></crow>
           <crow><td>source</td><td>Builds the source tarball in the dist directory</td></crow>
           <crow><td>tarball</td><td>Builds the binary distribution in the dist directory</td></crow>
         </ctable>

     <p>The tarball will includes the Castor JAR, all dependent library
        JARs, readme and license files, and all DTDs and XML schemas in
        the <tt>schema</tt> directory.</p>

        </section>

        <section title="Directory Structure">

             <ctable border="1">
               <crow><td>bin</td><td>Script/batch files required for building Castor, running samples, CTF et alias</td></crow>
               <crow><td>src/main</td><td>The source base for all the Castor modules</td></crow>
               <crow><td>src/doc</td><td>Documentation (in XML form)</td></crow>
               <crow><td>src/schema</td><td>DTD and XML schema for Castor mapping files</td></crow>
               <crow><td>src/examples</td><td>Examples for the various packages</td></crow>
               <crow><td>src/tests</td><td>Test cases for the various packages</td></crow>
               <crow><td>src/etc</td><td>Additional files that are not part of the code base</td></crow>
               <crow><td>lib</td><td>JARs required to build Castor and distributable JARs</td></crow>
               <crow><td>build/classes</td><td>When using Ant the Java classes are build in this directory</td></crow>
               <crow><td>build/doc</td><td>When using Ant the HTML documentation is build in this directory</td></crow>
               <crow><td>build/examples</td><td>When using the examples are build in this directory</td></crow>
               <crow><td>build/test</td><td>When using the test cases are build in this directory</td></crow>
               <crow><td>dist</td><td>The distribution directory</td></crow>
             </ctable>
         
        </section>
    
    </section>
    
  </body>
</document>
