c7bc43607b
PR: Obtained from: Submitted by: Reviewed by: git-svn-id: https://svn.apache.org/repos/asf/jakarta/poi/trunk@352310 13f79535-47bb-0310-9956-ffa450edef68
533 lines
17 KiB
HTML
533 lines
17 KiB
HTML
<html>
|
|
<head>
|
|
<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
|
|
<meta content="text/html; charset=ISO-8859-1">
|
|
<title>Contribution to POI</title>
|
|
<style type="text/css">
|
|
body { background-color: white; font-size: normal; color: black ; }
|
|
a { color: #525d76; }
|
|
a.black { color: #000000;}
|
|
table {border-width: 0; width: 100%}
|
|
table.centered {text-align: center}
|
|
table.title {text-align: center; width: 80%}
|
|
img{border-width: 0;}
|
|
span.s1 {font-family: Helvetica, Arial, sans-serif; font-weight: bold; color: #000000; }
|
|
span.s1_white { font-family: Helvetica, Arial, sans-serif; font-weight: bold; color: #ffffff; }
|
|
span.title {font-family: Helvetica, Arial, sans-serif; font-weight: bold; color: #000000; }
|
|
span.c1 {color: #000000; font-family: Helvetica, Arial, sans-serif}
|
|
tr.left {text-align: left}
|
|
hr { width: 100%; size: 2}
|
|
</style>
|
|
</head>
|
|
<body>
|
|
<table width="100%" cellspacing="0" cellpadding="0" border="0">
|
|
<tr>
|
|
<td valign="top" align="left"><a href="http://jakarta.apache.org/index.html"><img hspace="0" vspace="0" border="0" src="images/jakarta-logo.gif"></a></td><td width="100%" valign="top" align="left" bgcolor="#ffffff"><img hspace="0" vspace="0" border="0" align="right" src="images/header.gif"></td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="2" bgcolor="#525d76"><span class="c1"><a class="black" href="http://www.apache.org/">www.apache.org ></a><a class="black" href="http://jakarta.apache.org/">jakarta.apache.org ></a><a href="http://jakarta.apache.org/poi/" class="black">jakarta.apache.org/poi</a></span></td>
|
|
</tr>
|
|
<tr>
|
|
<td height="8"></td>
|
|
</tr>
|
|
</table>
|
|
<table border="0" cellpadding="0" cellspacing="0" width="100%">
|
|
<tr>
|
|
<td width="1%">
|
|
<br>
|
|
</td><td nowrap="1" valign="top" width="14%">
|
|
<br>
|
|
<span class="s1">About</span>
|
|
<br>
|
|
<a class="s1" href="index.html">Index</a>
|
|
<br>
|
|
<a class="s1" href="historyandfuture.html">History</a>
|
|
<br>
|
|
<a class="s1" href="historyandfuture.html">Future</a>
|
|
<br>
|
|
<a class="s1" href="http://jakarta.apache.org/builds/jakarta-poi/">Download</a>
|
|
<br>
|
|
<a class="s1" href="plan/POI10Vision.html">1.0 Vision</a>
|
|
<br>
|
|
<a class="s1" href="plan/POI20Vision.html">2.0 Vision</a>
|
|
<br>
|
|
<a class="s1" href="who.html">Who we are</a>
|
|
<br>
|
|
<a class="s1" href="changes.html">Changes</a>
|
|
<br>
|
|
<a class="s1" href="faq.html">FAQ</a>
|
|
<br>
|
|
<br>
|
|
<span class="s1">Sub-Projects</span>
|
|
<br>
|
|
<a class="s1" href="overview.html">Overview</a>
|
|
<br>
|
|
<a class="s1" href="poifs/index.html">POIFS</a>
|
|
<br>
|
|
<a class="s1" href="hssf/index.html">HSSF</a>
|
|
<br>
|
|
<a class="s1" href="hdf/index.html">HDF</a>
|
|
<br>
|
|
<a class="s1" href="hpsf/index.html">HPSF</a>
|
|
<br>
|
|
<a class="s1" href="utils/index.html">POI-Utils</a>
|
|
<br>
|
|
<br>
|
|
<span class="s1">References</span>
|
|
<br>
|
|
<a class="s1" href="inthenews.html">In The News</a>
|
|
<br>
|
|
<a class="s1" href="livesites.html">Live Sites</a>
|
|
<br>
|
|
<a class="s1" href="http://sc.openoffice.org/excelfileformat.pdf">XLS spec [PDF]</a>
|
|
<br>
|
|
<a class="s1" href="http://xml.apache.org/cocoon/">Apache Cocoon</a>
|
|
<br>
|
|
<a class="s1" href="resolutions/index.html">Resolutions</a>
|
|
<br>
|
|
<br>
|
|
<span class="s1">Get Involved</span>
|
|
<br>
|
|
<a class="s1" href="contrib.html">Contributing</a>
|
|
<br>
|
|
<a class="s1" href="http://nagoya.apache.org/bugzilla/buglist.cgi?product=POI">Bug Database</a>
|
|
<br>
|
|
<a class="s1" href="http://jakarta.apache.org/site/cvsindex.html">CVS</a>
|
|
<br>
|
|
<a class="s1" href="http://jakarta.apache.org/site/mail.html">Mail Lists</a>
|
|
<br>
|
|
</td><td width="1%">
|
|
<br>
|
|
</td><td align="left" valign="top" width="*">
|
|
<title>Contribution to POI</title>
|
|
<table width="100%" align="center" class="centered">
|
|
<tbody>
|
|
<tr>
|
|
<td align="center">
|
|
<table border="0" cellpadding="1" cellspacing="0" class="title">
|
|
<tbody>
|
|
<tr>
|
|
<td bgcolor="#525d76">
|
|
<table width="100%" border="0" cellpadding="2" cellspacing="0" class="centered">
|
|
<tbody>
|
|
<tr>
|
|
<td bgcolor="#f3dd61"><span class="title">Contribution to POI</span></td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<font size="-2" color="#000000">
|
|
<p>
|
|
<a href="mailto:"></a>
|
|
</p>
|
|
</font>
|
|
<div align="right">
|
|
<table cellspacing="0" cellpadding="2" border="0" width="100%">
|
|
<tr>
|
|
<td bgcolor="#525D76"><font color="#ffffff" size="+1"><font face="Arial,sans-serif"><b>Introduction</b></font></font></td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<br>
|
|
|
|
|
|
<p align="justify">
|
|
The POI Project is an <a href="http://www.opensource.org/">Open Source</a>
|
|
volunteer project released under a very open license.
|
|
This means there are many ways to contribute to the project - either
|
|
with direct participation (coding, documenting, answering questions,
|
|
proposing ideas, reporting bugs, suggesting bug fixes, etc. ...) or by resource
|
|
donations (money, time, publicity, hardware, software, conference
|
|
presentations, speeches, etc. ...).
|
|
</p>
|
|
|
|
<p align="justify">
|
|
To begin with, we suggest you subscribe to the
|
|
<a href="mail-lists.html">POI mailing lists</a>
|
|
(follow the link for information on how to subscribe and to access the mail
|
|
list archives). Listen in for a while, to hear how others make contributions.
|
|
</p>
|
|
|
|
|
|
<p align="justify">You can get your local working copy of the
|
|
<a href="http://jakarta.apache.org/site/cvsindex.html">latest and
|
|
greatest code</a> (which you find in the jakarta-poi module in
|
|
the CVS code repository. Review the <a href="todo.html">todo</a> list and choose a task
|
|
(or perhaps you have noticed something that needs patching). Make the changes, do the testing,
|
|
generate a patch, and post to the dev mailing list. (Do not worry - the process is easy and
|
|
explained below.)
|
|
</p>
|
|
|
|
|
|
<p align="justify">
|
|
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:
|
|
we have work for you! And we'll be very available to you for any questions!
|
|
</p>
|
|
|
|
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<br>
|
|
<div align="right">
|
|
<table cellspacing="0" cellpadding="2" border="0" width="100%">
|
|
<tr>
|
|
<td bgcolor="#525D76"><font color="#ffffff" size="+1"><font face="Arial,sans-serif"><b>Help Wanted Here</b></font></font></td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<br>
|
|
|
|
<p align="justify">
|
|
The rest of this document is mainly about
|
|
contributing new or improved code and/or documentation, but we would also be glad to have
|
|
extra help in any of the following areas:
|
|
</p>
|
|
|
|
<ul>
|
|
|
|
<li>Answering questions on the <code>users</code> mailing list - there is often a problem of
|
|
having too many questioners and not enough experts to respond to all the questions.</li>
|
|
|
|
<li>Testing POI (especially its less-frequently-used features) on various configurations
|
|
and reporting back.</li>
|
|
|
|
<li>Debugging - producing reproducible test cases and/or finding causes of bugs. Some known bugs are informally listed on
|
|
<a href="todo.html">To Do</a>, and some are recorded in Bugzilla
|
|
(see <a href="#procedure">explanation below</a>).</li>
|
|
|
|
<li>Specifying/analyzing/designing new features - and beyond. (If you wish to get involved
|
|
with this, please join the <code>general POI mailing list</code>
|
|
, install and try out POI
|
|
and read some of the <a href="mail-lists.html">mail archives</a>.
|
|
You should have a strong "fluency" in Java and a basic understanding of
|
|
the POI architecture - don't just say "it should have XYZ" without reading anything first -
|
|
because chances are, someone's already thought of that feature!)</li>
|
|
|
|
<li>Packaging easy-to-install packages (such as RPMs) for the myriad of possible configurations out
|
|
there. (The project does not maintain anything but the basic <code>.zip</code> and
|
|
<code>.tar.gz</code> packages, but anyone is welcome to build their own specific packages and
|
|
announce them on the <code>general POI list</code>)</li>
|
|
|
|
<li>... and there is just one other thing - don't forget to tell everyone who asks, how great POI is! ;-)
|
|
The more people that know about and start to use POI, the larger the pool of
|
|
potential contributors there will be.
|
|
</li>
|
|
|
|
</ul>
|
|
|
|
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<br>
|
|
<div align="right">
|
|
<table cellspacing="0" cellpadding="2" border="0" width="100%">
|
|
<tr>
|
|
<td bgcolor="#525D76"><font color="#ffffff" size="+1"><font face="Arial,sans-serif"><b>CVS Usage Precis</b></font></font></td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<br>
|
|
|
|
<p align="justify">An overview of how to use CVS to participate in POI development.
|
|
Do not be afraid - you cannot accidently destroy the actual code repository,
|
|
because you are working with a local copy as an anonymous user.
|
|
You do not have the system permissions to change anything. You can only
|
|
update your local repository and compare your revisions with the real
|
|
repository.
|
|
</p>
|
|
|
|
|
|
<p align="justify">
|
|
(Further general CVS usage information is at
|
|
<a href="http://www.cvshome.org/">www.cvshome.org</a> and your local
|
|
<code>info cvs</code> pages or <code>man cvs</code> pages or user
|
|
documentation.)
|
|
</p>
|
|
|
|
|
|
<p align="justify">
|
|
Let us lead by example. We will show you how to establish your local
|
|
repository, how to keep it up-to-date, and how to generate the differences
|
|
to create a patch. (The commands are for Linux.)
|
|
</p>
|
|
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<br>
|
|
<div align="right">
|
|
<table cellspacing="0" cellpadding="2" border="0" width="100%">
|
|
<tr>
|
|
<td bgcolor="#525D76"><font color="#ffffff" size="+1"><font face="Arial,sans-serif"><b>CVS Committer with Secure Shell access</b></font></font></td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<br>
|
|
|
|
<p align="justify">After a developer has consistently provided contributions (code,
|
|
documentation and discussion), then the rest of the dev community
|
|
may vote to grant this developer commit access to CVS.
|
|
</p>
|
|
|
|
|
|
<p align="justify">You will need secure access to the repository to be able to commit
|
|
patches. Here are some resources that help to get your machine configured
|
|
to use the repository over SSH.
|
|
</p>
|
|
|
|
|
|
<ul>
|
|
|
|
<li>
|
|
<a href="http://cvsbook.red-bean.com/">The CVS Book</a>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="http://www.cvshome.org/">www.cvshome.org</a>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="https://sourceforge.net/cvs/?group_id=32701"></a>
|
|
- See the bottom of the page for links to tips for UNIX and Windows.
|
|
Even if you are on UNIX, the Windows page will also help.</li>
|
|
|
|
</ul>
|
|
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<br>
|
|
<div align="right">
|
|
<table cellspacing="0" cellpadding="2" border="0" width="100%">
|
|
<tr>
|
|
<td bgcolor="#525D76"><font color="#ffffff" size="+1"><font face="Arial,sans-serif"><b>Procedure for Raising Development Issues</b></font></font></td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<br>
|
|
|
|
<p align="justify">
|
|
There are two methods for discussing development and submitting patches.
|
|
So that everyone can be productive, it is important to know which method
|
|
is appropriate for a certain situation and how to go about it without
|
|
confusion. This section explains when to use the
|
|
<code>developer</code> <a href="mail-lists.html">mailing list</a>
|
|
and the bug database.
|
|
</p>
|
|
|
|
|
|
<p align="justify">
|
|
Research your topic thoroughly before beginning to discuss a new
|
|
development issue. Search and browse through the email archives - your
|
|
issue may have been discussed before. Prepare your post clearly and
|
|
concisely.
|
|
</p>
|
|
|
|
|
|
<p align="justify">
|
|
Most issues will be discovered, resolved, and then patched quickly
|
|
via the <code>developer</code> mailing list. Larger issues, and ones that
|
|
are not yet fully understood or are hard to solve, are destined for
|
|
Bugzilla.
|
|
</p>
|
|
|
|
|
|
<p align="justify">
|
|
Experienced developers use Bugzilla directly, as they are very sure
|
|
when they have found a bug and when not. However, less experienced users
|
|
should first discuss it on the user or developer mailing list (as
|
|
appropriate). Impatient people frequently enter everything into Bugzilla
|
|
without caring if it is a bug in POI or their own
|
|
installation/configuration mistake - please, do not do this.
|
|
</p>
|
|
|
|
|
|
<p align="justify">
|
|
As a rule-of-thumb, discuss an issue on the <code>developers</code>
|
|
mailing list first to work out any details.
|
|
After it is confirmed to be worthwhile, and you are clear about it,
|
|
then submit the bug description or patch via Bug Tracking.
|
|
</p>
|
|
|
|
|
|
<p align="justify">
|
|
If you do not get any answer on your first attempt, post
|
|
your issue again until you get a reply. (But, please, not every hour - allow a few
|
|
days for the list to deal with it.) Do not be impatient - remember that
|
|
the whole world is busy, not just you. Bear in mind that other countries
|
|
will have holidays at different times to your country and that they are
|
|
in different time zones. You might also consider re-writing your initial
|
|
posting - perhaps it was not clear enough
|
|
and the readers' eyes glazed over.
|
|
</p>
|
|
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<br>
|
|
<div align="right">
|
|
<table cellspacing="0" cellpadding="2" border="0" width="100%">
|
|
<tr>
|
|
<td bgcolor="#525D76"><font color="#ffffff" size="+1"><font face="Arial,sans-serif"><b>Contribution Notes and Tips</b></font></font></td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<br>
|
|
|
|
<p align="justify">
|
|
This is a collection of tips for contributing to the project in a manner
|
|
that is productive for all parties.
|
|
</p>
|
|
|
|
|
|
<ul>
|
|
|
|
<li>
|
|
Every contribution is worthwhile. Even if the ensuing discussion
|
|
proves it to be off-beam, then it may jog ideas for other people.
|
|
</li>
|
|
|
|
<li>
|
|
Use sensible and concise email subject headings. Search engines, and
|
|
humans trying to browse a voluminous list, will respond favorably to a
|
|
descriptive title.
|
|
</li>
|
|
|
|
<li>Start new threads with new Subjects for new topics, rather than
|
|
re-using the previous Subject line.
|
|
</li>
|
|
|
|
<li>Keep each topic focussed. If some new topic arises, start a new
|
|
discussion. This leaves the original topic to continue un-cluttered.
|
|
</li>
|
|
|
|
<li>Whenever you decide to start a new topic, then start with a fresh
|
|
new email message window. Do not use the "Reply to" button,
|
|
because threaded mail-readers get confused (they use the
|
|
<code>In-reply-to</code> header). Otherwise, your new topic will get
|
|
lost in the previous thread and go un-answered.
|
|
</li>
|
|
|
|
<li>
|
|
Prepend your email subject line with a marker when that is appropriate,
|
|
e.g. <code>[Patch]</code>, <code>[Proposal]</code>,
|
|
<code>[RT]</code> (Random Thought, these quickly blossom into research
|
|
topics :-), <code>[STATUS]</code> (development status of a certain
|
|
feature).
|
|
</li>
|
|
|
|
<li>
|
|
When making changes to XML documentation, or any XML document for that
|
|
matter, use a
|
|
<a href="http://www.oasis-open.org/cover/">validating parser</a>
|
|
(one that is tried and true is
|
|
<a href="http://www.jclark.com/sp/">SP/nsgmls</a>).
|
|
This procedure will detect errors without having to go through the whole
|
|
<code>build docs</code> process to find them. Do not expect POI
|
|
or the build system to detect the validation errors for you - they can
|
|
do it, but that is not their purpose. (Anyway, nsgmls validation error
|
|
messages are more informative.). Andy wishes it to be known he uses
|
|
<a href="http://www.sourceforge.net/projects/jedit">jEdit</a>. For
|
|
his XML editing. (That is when he's not hacking it in 'vi' the true editor
|
|
and light of the text editing world!).
|
|
</li>
|
|
|
|
<li>
|
|
Remember that most people are participating in development on a
|
|
volunteer basis and in their "spare time". These enthusiasts will attempt
|
|
to respond to issues. It may take a little while to get your answers.
|
|
</li>
|
|
|
|
<li>
|
|
Research your topic thoroughly before beginning to discuss a new
|
|
development issue. Search and browse through the email archives - your
|
|
issue may have been discussed before. Do not just perceive a problem and
|
|
then rush out with a question - instead, delve.
|
|
</li>
|
|
|
|
<li>
|
|
Try to at least offer a partial solution and not just a problem statement.
|
|
</li>
|
|
|
|
<li>
|
|
Take the time to clearly explain your issue and write a concise email
|
|
message. Less confusion facilitates fast and complete resolution.
|
|
</li>
|
|
|
|
<li>
|
|
Do not bother to send an email reply that simply says "thanks".
|
|
When the issue is resolved, that is the finish - end of thread.
|
|
Reduce clutter.
|
|
</li>
|
|
|
|
<li>
|
|
You would usually do any development work against the HEAD branch of CVS.
|
|
</li>
|
|
|
|
<li>
|
|
When sending a patch, you usually do not need to worry about which CVS
|
|
branch it should be applied to. The maintainers of the repository will
|
|
decide.
|
|
</li>
|
|
|
|
<li>
|
|
If an issue starts to get bogged down in list discussion, then it may
|
|
be appropriate to go into private off-list discussion with a few interested
|
|
other people. Spare the list from the gory details. Report a summary back
|
|
to the list to finalize the thread.
|
|
</li>
|
|
|
|
<li>
|
|
Become familiar with the mailing lists. As you browse and search, you will
|
|
see the way other people do things. Follow the leading examples.
|
|
</li>
|
|
|
|
</ul>
|
|
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<br>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<br>
|
|
<table width="100%" border="0" cellspacing="0" cellpadding="0">
|
|
<tbody>
|
|
<tr>
|
|
<td>
|
|
<hr noshade="" size="1">
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td align="center"><i>Copyright © 2002 Apache Software Foundation</i></td>
|
|
</tr>
|
|
<tr>
|
|
<td align="right" width="100%">
|
|
<br>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td align="right" width="100%"><a href="http://krysalis.org/"><img alt="Krysalis Logo" src="images/krysalis-compatible.jpg"></a><a href="http://xml.apache.org/cocoon/"><img alt="Cocoon Logo" src="images/built-with-cocoon.gif"></a></td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</body>
|
|
</html>
|