124 lines
6.4 KiB
XML
124 lines
6.4 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!--
|
|
====================================================================
|
|
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.
|
|
====================================================================
|
|
-->
|
|
<!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</title>
|
|
<section><title>Disclaimer</title>
|
|
<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</title>
|
|
<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</title>
|
|
<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</title>
|
|
<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="../subversion.html">Subversion</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://issues.apache.org/bugzilla/buglist.cgi?product=POI">Bug database</link> for suggestions.</li>
|
|
</ul>
|
|
</section>
|
|
<section><title>Submitting Patches</title>
|
|
<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. 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 poi directory.
|
|
You'll attach both files in the next step.
|
|
</p>
|
|
<p>
|
|
Patches are submitted via the <link href="http://issues.apache.org/bugzilla/buglist.cgi?product=POI">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://poi.apache.org/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>
|