<!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>Apache POI - Contribution Guidelines</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 width="50%" 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 width="50%" align="right">
<div align="right" 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="guidelines.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">Overview</span>
<div class="menuItem">
<a href="index.html">Home</a>
</div>
<div class="menuItem">
<a href="download.html">Download</a>
</div>
<div class="menuItem">
<a href="overview.html">Components</a>
</div>
<div class="menuItem">
<a href="text-extraction.html">Text Extraction</a>
</div>
<div class="menuItem">
<a href="encryption.html">Encryption support</a>
</div>
<div class="menuItem">
<a href="casestudies.html">Case Studies</a>
</div>
<div class="menuItem">
<a href="legal.html">Legal</a>
</div>
</div>
<div class="menu">
<span class="menuLabel">Help</span>
<div class="menuItem">
<a href="apidocs/index.html">Javadocs</a>
</div>
<div class="menuItem">
<a href="faq.html">FAQ</a>
</div>
<div class="menuItem">
<a href="mailinglists.html">Mailing Lists</a>
</div>
<div class="menuItem">
<a href="http://issues.apache.org/bugzilla/buglist.cgi?product=POI">Bug Database</a>
</div>
<div class="menuItem">
<a href="changes.html">Changes Log</a>
</div>
</div>
<div class="menu">
<span class="menuLabel">Getting Involved</span>
<div class="menuItem">
<a href="subversion.html">Subversion Repository</a>
</div>
<div class="menuItem">
<a href="howtobuild.html">How To Build</a>
</div>
<div class="menuItem">
<span class="menuSelected">Contribution Guidelines</span>
</div>
<div class="menuItem">
<a href="who.html">Who We Are</a>
</div>
</div>
<div class="menu">
<span class="menuLabel">Component APIs</span>
<div class="menuItem">
<a href="spreadsheet/index.html">Excel (SS=HSSF+XSSF)</a>
</div>
<div class="menuItem">
<a href="hwpf/index.html">Word (HWPF+XWPF)</a>
</div>
<div class="menuItem">
<a href="slideshow/index.html">PowerPoint (HSLF+XSLF)</a>
</div>
<div class="menuItem">
<a href="oxml4j/index.html">OpenXML4J (OOXML)</a>
</div>
<div class="menuItem">
<a href="poifs/index.html">OLE2 Filesystem (POIFS)</a>
</div>
<div class="menuItem">
<a href="hpsf/index.html">OLE2 Document Props (HPSF)</a>
</div>
<div class="menuItem">
<a href="hsmf/index.html">Outlook (HSMF)</a>
</div>
<div class="menuItem">
<a href="hdgf/index.html">Visio (HDGF)</a>
</div>
<div class="menuItem">
<a href="hmef/index.html">TNEF (HMEF)</a>
</div>
<div class="menuItem">
<a href="hpbf/index.html">Publisher (HPBF)</a>
</div>
</div>
<div class="menu">
<span class="menuLabel">Apache Wide</span>
<div class="menuItem">
<a href="http://www.apache.org/">Apache Software Foundation</a>
</div>
<div class="menuItem">
<a href="http://www.apache.org/licenses/">License</a>
</div>
<div class="menuItem">
<a href="http://www.apache.org/foundation/sponsorship.html">Sponsorship</a>
</div>
<div class="menuItem">
<a href="http://www.apache.org/foundation/thanks.html">Thanks</a>
</div>
<div class="menuItem">
<a href="http://www.apache.org/security/">Security</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">
Search Apache POI<br>
<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"></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>Apache POI - Contribution Guidelines</h1>
</div>
<div class="h3">
<a name="Introduction"></a>
<div class="h3">
<h3>Introduction</h3>
</div>
<a name="Disclaimer"></a>
<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>
<a name="The+Licensing"></a>
<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>
<a name="Publicly+Available+Information+on+the+file+formats"></a>
<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>
<a name="I+just+signed+an+NDA+to+get+a+spec+from+Microsoft+and+I%27d+like+to+contribute"></a>
<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. Most of this Public
Information currently comes from the documentation that Microsoft
makes freely available (see above). The rest of the 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
received such information from a person bound by such an agreement, you
cannot participate in this project. Sorry. Well, unless you can persuade
Microsoft to release you from the terms of the NDA on the grounds that
most of the information is now publically available. However, if you have
been party to a Microsoft NDA, you will need to get clearance from Microsoft
before contributing.
</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, and have only made us of the public documentation.
</p>
<a name="I+just+want+to+get+involved+but+don%27t+know+where+to+start"></a>
<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 <a href="mailinglists.html">mailing lists</a> 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>Contribute examples - if there's something people are often asking about on the <a href="mailinglists.html">user list</a> which isn't covered in the documentation or current examples, try writing an example of this and uploading it as a patch.</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>Check the <a href="http://issues.apache.org/bugzilla/buglist.cgi?product=POI">bug database</a> for simple problem reports, and write a patch to fix the problem</li>
<li>Review existing patches in the <a href="http://issues.apache.org/bugzilla/buglist.cgi?product=POI">bug database</a>, and report if they still apply, if they need unit tests atc.</li>
<li>Take a look at all the <a href="https://issues.apache.org/bugzilla/buglist.cgi?product=POI;bug_status=NEW;bug_status=NEEDINFO">unresolved issues in the bug database</a>, and see if you can help with testing or patches for them</li>
<li>Add in new features, see <a href="http://issues.apache.org/bugzilla/buglist.cgi?product=POI">Bug database</a> for suggestions.</li>
</ul>
<p>The Apache <a href="http://www.apache.org/dev/contributors.html">Contributors Tech Guide</a> gives a good overview how to start contributing patches.</p>
<p>The Nutch project also have a very useful guide on becoming a
new developer in their project. While it is written for their project,
a large part of it will apply to POI too. You can read it at
<a href="http://wiki.apache.org/nutch/Becoming_A_Nutch_Developer">http://wiki.apache.org/nutch/Becoming_A_Nutch_Developer</a>. The
<a href="http://community.apache.org/">Apache Community Development
Project</a> also provides guidance and mentoring for new contributors.</p>
<a name="Submitting+Patches"></a>
<div class="h3">
<h3>Submitting Patches</h3>
</div>
<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>
Ideally, patches should be submitted early and often. This is for
two key reasons. Firstly, it's much easier to review smaller patches
than large ones. This means that smaller patches are much more likely
to be applied to SVN in a timely fashion. Secondly, by sending in your
patches earlier rather than later, it's much easier to get feedback
on your coding and direction. If you've missed an easier way to do something,
or are duplicating some (probably hidden) existing code, or taking things
in an unusual direction, it's best to get the feedback sooner rather than
later! As such, when submitting patches to POI, as with other Apache
Software Foundation projects, do please try to submit early and often, rather
than "throwing a large patch over the wall" at the end.
</p>
<p>You may create your patch file using either of the following approaches (the committers recommend the first):</p>
<a name="Approach+1+-+use+Ant"></a>
<div class="h4">
<h4>Approach 1 - use Ant</h4>
</div>
<p>Use Ant to generate a patch file to POI: </p>
<pre class="code">
ant -f patch.xml
</pre>
<p>
This will create a file named patch.tar.gz that will contain a unified diff of files that have been modified
and also include files that have been added. Review the file for completeness and correctness. This approach
is recommended because it standardizes the way in which patch files are constructed. It also eliminates the
chance of you missing to submit new files that constitute part of the patch.
</p>
<a name="Approach+2+-+the+manual+way"></a>
<div class="h4">
<h4>Approach 2 - the manual way</h4>
</div>
<p>
Patches to existing files should be generated with svn diff filename and save the output to a file.
if you want to get the changes made to multiple files in a directory , just use svn diff.
then, tar and gzip the patch file as well as any new files that you have added.
</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>
<a name="checklist+before+submitting+a+patch"></a>
<div class="h4">
<h4>checklist before submitting a patch</h4>
</div>
<ul>
<li>added code complies with <a href="http://poi.apache.org/resolutions/res001.html">coding standards</a>
</li>
<li>added code compiles and runs on java 1.5</li>
<li>new java files begin with the <a href="http://www.apache.org/foundation/licence-faq.html">
apache software license</a> statement.</li>
<li>the code does not depend on gpl or lgpl code.</li>
<li>the code includes the @author tag on any files you've altered or created.</li>
<li>existing test cases succeed.</li>
<li>new test cases written and succeed.</li>
<li>documentation page extended as appropriate.</li>
<li>diff files generated using svn diff</li>
<li>message to dev contains [patch], task name and patch reason in subject.</li>
<li>message body contains a rationale for the patch.</li>
<li>message attachment contains the patch file(s).</li>
</ul>
<a name="Mentoring+and+Committership"></a>
<div class="h3">
<h3>Mentoring and Committership</h3>
</div>
<p>The POI project will generally offer committership to contributors who send
in consistently good patches over a period of several months.</p>
<p>The requirement for "good patches" generally means patches which can be applied
to SVN with little or no changes. These patches should include unit test, and
appropriate documentation. Whilst your first patch to POI may require quite a
bit of work before it can be committed by an existing committer, with any luck
your later patches will be applied with no / minor tweaks. Please do take note
of any changes required by your earlier patches, to learn for later ones! If
in doubt, ask on the <a href="mailinglists.html">dev mailing list</a>.</p>
<p>The requirement for patches over several months is to ensure that committers
remain with the project. It's very easy for a good developer to fire off half
a dozen good patches in the couple of weeks that they're working on a POI
powered project. However, if that developer then moves away, and stops
contributing to POI after that spurt, then they're not a good candidate for
committership. As such, we generally require people to stay around for a while,
submitting patches and helping on the mailing list before considering them
for committership.</p>
<p>Where possible, patches should be submitted early and often. For more details
on this, please see the "Submitting Patches" section above.</p>
<p>Where possible, the existing developers will try to help and mentor new
contributors. However, everyone involved in POI is a volunteer, and it may
happen that your first few patches come in at a time when all the committers
are very busy. Do please have patience, and remember to use the
<a href="mailinglists.html">dev mailing list</a> so that other
contributors can assist you!</p>
<p>For more information on getting started at Apache, mentoring, and local
Apache Committers near you who can offer advice, please see the
<a href="http://community.apache.org/">Apache Community Development
Project</a> website.</p>
<div id="authors" align="right">by Nick Burch, David Fisher</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-2011 The Apache Software Foundation. All rights reserved.<br>
Apache POI, POI, Apache, the Apache feather logo, and the Apache
POI project logo are trademarks of The Apache Software Foundation.
</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"></div>
</div>
<!--================= end Credits ==================-->
</td>
</tr>
</tbody>
</table>
</div>
<!--================= end Footer ==================-->
</body>
</html>
