<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <html> <head> <META http-equiv="Content-Type" content="text/html; charset=UTF-8"> <!--*** This is a generated file. Do not edit. ***--> <link rel="stylesheet" href="../skin/tigris.css" type="text/css"> <link rel="stylesheet" href="../skin/mysite.css" type="text/css"> <link rel="stylesheet" href="../skin/site.css" type="text/css"> <link media="print" rel="stylesheet" href="../skin/print.css" type="text/css"> <title>Contribution to POI</title> </head> <body bgcolor="white" class="composite"> <!--================= start Banner ==================--> <div id="banner"> <table width="100%" cellpadding="8" cellspacing="0" summary="banner" border="0"> <tbody> <tr> <!--================= start Group Logo ==================--> <td align="left"> <div class="groupLogo"> <a href="http://poi.apache.org"><img border="0" class="logoImage" alt="Apache POI" src="../resources/images/group-logo.jpg"></a> </div> </td> <!--================= end Group Logo ==================--> <!--================= start Project Logo ==================--><td align="right"> <div class="projectLogo"> <a href="http://poi.apache.org/"><img border="0" class="logoImage" alt="POI" src="../resources/images/project-logo.jpg"></a> </div> </td> <!--================= end Project Logo ==================--> </tr> </tbody> </table> </div> <!--================= end Banner ==================--> <!--================= start Main ==================--> <table width="100%" cellpadding="0" cellspacing="0" border="0" summary="nav" id="breadcrumbs"> <tbody> <!--================= start Status ==================--> <tr class="status"> <td> <!--================= start BreadCrumb ==================--><a href="http://www.apache.org/">Apache</a> | <a href="http://poi.apache.org/">POI</a><a href=""></a> <!--================= end BreadCrumb ==================--></td><td id="tabs"> <!--================= start Tabs ==================--> <div class="tab"> <span class="selectedTab"><a class="base-selected" href="../index.html">Home</a></span> | <script language="Javascript" type="text/javascript"> function printit() { if (window.print) { window.print() ; } else { var WebBrowser = '<OBJECT ID="WebBrowser1" WIDTH="0" HEIGHT="0" CLASSID="CLSID:8856F961-340A-11D0-A96B-00C04FD705A2"></OBJECT>'; document.body.insertAdjacentHTML('beforeEnd', WebBrowser); WebBrowser1.ExecWB(6, 2);//Use a 1 vs. a 2 for a prompting dialog box WebBrowser1.outerHTML = ""; } } </script><script language="Javascript" type="text/javascript"> var NS = (navigator.appName == "Netscape"); var VERSION = parseInt(navigator.appVersion); if (VERSION > 3) { document.write(' <a title="PRINT this page OUT" href="javascript:printit()">PRINT</a>'); } </script> | <a title="PDF file of this page" href="index.pdf">PDF</a> </div> <!--================= end Tabs ==================--> </td> </tr> </tbody> </table> <!--================= end Status ==================--> <table id="main" width="100%" cellpadding="8" cellspacing="0" summary="" border="0"> <tbody> <tr valign="top"> <!--================= start Menu ==================--> <td id="leftcol"> <div id="navcolumn"> <div class="menuBar"> <div class="menu"> <span class="menuLabel">Apache POI</span> <div class="menuItem"> <a href="../index.html">Top</a> </div> </div> <div class="menu"> <span class="menuLabel">Get Involved</span> <div class="menuItem"> <span class="menuSelected">Contributing</span> </div> <div class="menuItem"> <a href="branching.html">Branching</a> </div> <div class="menuItem"> <a href="../subversion.html">Subversion</a> </div> <div class="menuItem"> <a href="../mailinglists.html">Mail Lists</a> </div> </div> </div> </div> <form target="_blank" action="http://www.google.com/search" method="get"> <table summary="search" border="0" cellspacing="0" cellpadding="0"> <tr> <td><img height="1" width="1" alt="" src="../skin/images/spacer.gif" class="spacer"></td><td nowrap="nowrap"><input value="poi.apache.org" name="sitesearch" type="hidden"><input size="10" name="q" id="query" type="text"><img height="1" width="5" alt="" src="../skin/images/spacer.gif" class="spacer"><input name="Search" value="GO" type="submit"> <br> Search poi</td><td><img height="1" width="1" alt="" src="../skin/images/spacer.gif" class="spacer"></td> </tr> <tr> <td colspan="3"><img height="7" width="1" alt="" src="../skin/images/spacer.gif" class="spacer"></td> </tr> <tr> <td class="bottom-left-thick"></td><td bgcolor="#a5b6c6"><img height="1" width="1" alt="" src="../skin/images/spacer.gif" class="spacer"></td><td class="bottom-right-thick"></td> </tr> </table> </form> </td> <!--================= end Menu ==================--> <!--================= start Content ==================--><td> <div id="bodycol"> <div class="app"> <div align="center"> <h1>Contribution to POI</h1> </div> <div class="h3"> <div class="h3"> <h3>Introduction</h3> </div> <div class="h4"> <h4>Disclaimer</h4> </div> <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> <div class="h4"> <h4>The Licensing</h4> </div> <p> The POI project is <a href="http://www.opensource.org">OpenSource</a> and developed/distributed under the <a href="http://www.apache.org/foundation/licence-FAQ.html"> Apache Software License</a>. 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> <div class="h4"> <h4>Publicly Available Information on the file formats</h4> </div> <p> In early 2008, Microsoft made a fairly complete set of documentation on the binary file formats freely and publicly available. These were released under the <a href="http://www.microsoft.com/interop/osp">Open Specification Promise</a>, which does allow us to use them for building open source software under the <a href="http://www.apache.org/foundation/licence-FAQ.html"> Apache Software License</a>. </p> <p> You can download the documentation on Excel, Word, PowerPoint and Escher (drawing) from <a href="http://www.microsoft.com/interop/docs/OfficeBinaryFormats.mspx">http://www.microsoft.com/interop/docs/OfficeBinaryFormats.mspx</a>. Documentation on a few of the supporting technologies used in these file formats can be downloaded from <a href="http://www.microsoft.com/interop/docs/supportingtechnologies.mspx">http://www.microsoft.com/interop/docs/supportingtechnologies.mspx</a>. </p> <p> Previously, Microsoft published a book on the Excel 97 file format. It can still be of plenty of use, and is handy dead tree form. Pick up a copy of "Excel 97 Developer's Kit" from your favourite second hand book store. </p> <p> The newer Office Open XML (ooxml) file formats are documented as part of the ECMA / ISO standardisation effort for the formats. This documentation is quite large, but you can normally find the bit you need without too much effort! This can be downloaded from <a href="http://www.ecma-international.org/publications/standards/Ecma-376.htm">http://www.ecma-international.org/publications/standards/Ecma-376.htm</a>, and is also under the <a href="http://www.microsoft.com/interop/osp">OSP</a>. </p> <p> It is also worth checking the documentation and code of the other open source implementations of the file formats. </p> <div class="h4"> <h4>I just signed an NDA to get a spec from Microsoft and I'd like to contribute</h4> </div> <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 (possibly 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 have only ever read the publicly available file format information, and not any received under an NDA or similar. </p> <div class="h3"> <h3>I just want to get involved but don't know where to start</h3> </div> <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 <a href="../subversion.html">Subversion</a> 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>Download the file format documentation from Microsoft - <a href="http://www.microsoft.com/interop/docs/OfficeBinaryFormats.mspx">OLE2 Binary File Formats</a> or <a href="http://www.ecma-international.org/publications/standards/Ecma-376.htm">OOXML XML File Formats</a> </li> <li>Submit patches (see below) of your contributions, modifications.</li> <li>Fill out new features, see <a href="http://issues.apache.org/bugzilla/buglist.cgi?product=POI">Bug database</a> for suggestions.</li> </ul> <div class="h3"> <h3>Submitting Patches</h3> </div> <p> Create patches by getting the latest sources from Subversion. Alter or add files as appropriate. Then, from the poi directiory, type svn diff > mypatch.patch. This will capture all of your changes in a patch file of the appropriate format. However, svn diff won't capture any new files you may have added. So, 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 poi directory. You'll attach both files in the next step. </p> <p> Patches are submitted via the <a href="http://issues.apache.org/bugzilla/buglist.cgi?product=POI">Bug Database</a>. 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 <a href="http://poi.apache.org/resolutions/res001.html">Coding Standards</a>). Patches that are of low quality may be rejected or the contributer may be asked to bring them up to spec. </p> <p>If you use a unix shell, you may find the following following sequence of commands useful for building the files to attach.</p> <pre class="code"> # Run this in the root of the checkout, i.e. the directory holding # build.xml and poi.pom # Build the directory to hold new files mkdir /tmp/poi-patch/ mkdir /tmp/poi-patch/new-files/ # Get changes to existing files svn diff > /tmp/poi-patch/diff.txt # Capture any new files, as svn diff won't include them # Preserve the path svn status | grep "^\?" | awk '{printf "cp --parents %s /tmp/poi-patch/new-files/\n", $2 }' | sh -s # tar up the new files cd /tmp/poi-patch/new-files/ tar jcvf ../new-files.tar.bz2 cd .. # Upload these to bugzilla echo "Please upload to bugzilla:" echo " /tmp/poi-patch/diff.txt" echo " /tmp/poi-patch/new-files.tar.bz2" </pre> <div id="authors" align="right">by Nicola Ken Barozzi, Marc Johnson, Andrew C. Oliver, Tetsuya Kitahata</div> </div> </div> </div> </td> <!--================= end Content ==================--> </tr> </tbody> </table> <!--================= end Main ==================--> <!--================= start Footer ==================--> <div id="footer"> <table summary="footer" cellspacing="0" cellpadding="4" width="100%" border="0"> <tbody> <tr> <!--================= start Copyright ==================--> <td colspan="2"> <div align="center"> <div class="copyright"> Copyright © 2002-2007 The Apache Software Foundation. All rights reserved. </div> </div> </td> <!--================= end Copyright ==================--> </tr> <tr> <td align="left"> <!--================= start Host ==================--> <!--================= end Host ==================--></td><td align="right"> <!--================= start Credits ==================--> <div align="right"> <div class="credit"> <a href="http://validator.w3.org/check/referer"><img width="88" height="31" alt="Valid HTML 4.01!" src="../skin/images/valid-html401.png" class="logoImage"></a><a href="http://jigsaw.w3.org/css-validator/"><img width="88" height="31" alt="Valid CSS!" src="../skin/images/vcss.png" class="logoImage"></a><a href="http://xml.apache.org/forrest/"><img border="0" class="logoImage" alt="Built with Apache Forrest" src="../images/built-with-forrest-button.png" width="88" height="31"></a> </div> </div> <!--================= end Credits ==================--> </td> </tr> </tbody> </table> </div> <!--================= end Footer ==================--> </body> </html>