<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "./dtd/document-v11.dtd">

<document>
 <header>
  <title>Contribution to POI</title>
  <authors>
   <person name="Nicola Ken Barozzi" email="barozzi@nicolaken.com"/> 
   <person name="Marc Johnson" email="mjohnson@apache.org"/>
   <person name="Andrew C. Oliver" email="acoliver@apache.org"/>
   <person name="Tetsuya Kitahata" email="tetsuya.kitahata@nifty.com"/>
   </authors>
 </header>

 <body>

 <section title="Introduction">
  <section title="Disclaimer">
   <p>
     Any information in here that might be perceived as legal information is 
     informational only.  We're not lawyers, so consult a legal professional
     if needed. 
   </p>
  </section>
  <section title="The Licensing">
   <p>
     The POI project is <link href="http://www.opensource.org">OpenSource</link>
     and developed/distributed under the <link 
     href="http://www.apache.org/foundation/licence-FAQ.html">
     Apache Software License</link>.  Unlike other licenses this license allows
     free open source development; however, it does not require you to release
     your source or use any particular license for your source.  If you wish
     to contribute to POI (which you're very welcome and encouraged to do so)
     then you must agree to release the rights of your source to us under this
     license.
   </p>
  </section>
  <section title="I just signed an NDA to get a spec from Microsoft and I'd like to contribute">
   <p>
     In short, stay away, stay far far away.  Implementing these file formats
     in POI is done strictly by using public information.  Public information
     includes sources from other open source projects, books that state the 
     purpose intended is for allowing implementation of the file format and 
     do not require any non-disclosure agreement and just hard work. 
     We are intent on keeping it
     legal, by contributing patches you agree to do the same.
   </p>
   <p> 
     If you've ever received information regarding the OLE 2 Compound Document
     Format under any type of exclusionary agreement from Microsoft, or  
     (probably illegally) received such information from a person bound by
     such an agreement, you cannot participate in this project.  (Sorry)
   </p>
   <p>
     Those submitting patches that show insight into the file format may be 
     asked to state explicitly that they are eligible or possibly sign an 
     agreement.
   </p>
  </section>
 </section>
  <section title="I just want to get involved but don't know where to start">
   <ul>
     <li>Read the rest of the website, understand what POI is and what it does,
         the project vision, etc.</li>
     <li>Use POI a bit, look for gaps in the documentation and examples.</li>
     <li>Join the mail lists and share your knowledge with others.</li>
     <li>Get <link href="http://jakarta.apache.org/site/cvsindex.html">CVS</link> and check out the POI source tree</li>
     <li>Documentation is always the best place to start contributing, maybe you found that if the documentation just told you how to do X then it would make more sense, modify the documentation.</li>
     <li>Get used to building POI, you'll be doing it a lot, be one with the build, know its targets, etc.</li>
     <li>Write Unit Tests.  Great way to understand POI.  Look for classes that aren't tested, or aren't tested on a public/protected method level, start there.</li>
     <li>(HSSF)Get the Excel 97 Developer's Kit - its out of print but its dirt cheap (seen copies for under $15 (US)) used on <link href="http://www.amazon.com">amazon</link>.  It explains the Excel file format.</li>
     <li>Submit patches (see below) of your contributions, modifications.</li>
     <li>Fill out new features, see <link href="http://jakarta.apache.org/site/bugs.html">Bug database</link> for suggestions.</li>
   </ul>
  </section>
  <section title="Submitting Patches"> 
   <p>
     Create patches by getting the latest sources from CVS (the HEAD).
     Alter or add files as appropriate.  Then, from the jakarta-poi directiory,
     type cvs diff -u > mypatch.patch.  This will capture all of your changes
     in a patch file of the appropriate format.  Next, if you've added any 
     files, create an archive (tar.bz2 preferred as its the smallest) in a 
     path-preserving archive format, relative to your jakarta-poi directory. 
     (Note: If you use <a href="http://www.wincvs.org/">WinCVS</a>, move to 
     [Admin] -&gt; [Command Line] Menu and type "cvs diff -u" at 
     [Enter a cvs line command] input field ([Commandline Settings] Tab), 
     while selecting the target directories or files, in order to create 
     unified diffs. 
     In other words, [Alt+A]+[Alt+C]+[Alt+C] and type "cvs diff -u".) 
     You'll attach both files in the next step.
   </p>
   <p> 
     Patches are submitted via the <link href="http://jakarta.apache.org/site/bugs.html">Bug Database</link>.  
     Create a new bug, set the subject to [PATCH] followed by a brief description.  Explain you patch and any special instructions and submit/save it.  
     Next, go back to the bug, and create attachements for the patch files you
     created.  Be sure to describe not only the files purpose, but its format. 
     (Is that ZIP or a tgz or a bz2 or what?).
   </p>
   <p>
     Make sure your patches include the @author tag on any files you've altered
     or created.  Make sure you've documented your changes and altered the 
     examples/etc to reflect them.  Any new additions should have unit tests.
     Lastly, ensure that you've provided approriate javadoc.  (see 
     <link href="http://jakarta.apache.org/poi/resolutions/res001.html">Coding
     Standards</link>).  Patches that are of low quality may be rejected or 
     the contributer may be asked to bring them up to spec.
   </p>
  </section>

</body>
</document>
