531 lines
17 KiB
HTML
531 lines
17 KiB
HTML
|
<html>
|
||
|
<head>
|
||
|
<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
|
||
|
<title>Contribution to POI</title>
|
||
|
</head>
|
||
|
<body bgcolor="#ffffff" marginheight="4" marginwidth="4" leftmargin="4" topmargin="4" alink="#023264" vlink="#023264" link="#525D76" text="#000000">
|
||
|
<table border="0" cellpadding="0" cellspacing="0" width="100%">
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><a href="http://jakarta.apache.org/index.html"><img src="images/jakarta-logo.gif" border="0" vspace="0" hspace="0"></a></td><td bgcolor="#ffffff" align="left" valign="top" width="100%"><img src="images/header.gif" align="right" border="0" vspace="0" hspace="0"></td>
|
||
|
</tr>
|
||
|
<tr>
|
||
|
<td colspan="2" height="2" width="100%">
|
||
|
<hr size="1" noshade="">
|
||
|
</td>
|
||
|
</tr>
|
||
|
</table>
|
||
|
<table border="0" cellpadding="0" cellspacing="0" width="100%">
|
||
|
<tr>
|
||
|
<td valign="top" width="1%"></td><td nowrap="1" valign="top" width="14%">
|
||
|
<br>
|
||
|
<font face="arial,helvetica,sanserif">
|
||
|
<br>
|
||
|
<font size="+1" color="#000000">Main</font><font size="-1">
|
||
|
<ul>
|
||
|
<li>
|
||
|
<a href="http://jakarta.apache.org"><font size="-1">Jakarta</font></a>
|
||
|
</li>
|
||
|
</ul>
|
||
|
</font>
|
||
|
<br>
|
||
|
<font size="+1" color="#000000">About</font><font size="-1">
|
||
|
<ul>
|
||
|
<li>
|
||
|
<a href="index.html"><font size="-1">Index</font></a>
|
||
|
</li>
|
||
|
<li>
|
||
|
<a href="historyandfuture.html"><font size="-1">History</font></a>
|
||
|
</li>
|
||
|
<li>
|
||
|
<a href="historyandfuture.html"><font size="-1">Future</font></a>
|
||
|
</li>
|
||
|
<li>
|
||
|
<a href="http://sourceforge.net/project/showfiles.php?group_id=32701"><font size="-1">Download</font></a>
|
||
|
</li>
|
||
|
<li>
|
||
|
<a href="plan/POI10Vision.html"><font size="-1">1.0 Vision</font></a>
|
||
|
</li>
|
||
|
<li>
|
||
|
<a href="plan/POI20Vision.html"><font size="-1">2.0 Vision</font></a>
|
||
|
</li>
|
||
|
<li>
|
||
|
<a href="who.html"><font size="-1">Who we are</font></a>
|
||
|
</li>
|
||
|
<li>
|
||
|
<a href="changes.html"><font size="-1">Changes</font></a>
|
||
|
</li>
|
||
|
<li>
|
||
|
<a href="todo.html"><font size="-1">Todo</font></a>
|
||
|
</li>
|
||
|
</ul>
|
||
|
</font>
|
||
|
<br>
|
||
|
<font size="+1" color="#000000">Sub-Projects</font><font size="-1">
|
||
|
<ul>
|
||
|
<li>
|
||
|
<a href="overview.html"><font size="-1">Overview</font></a>
|
||
|
</li>
|
||
|
<li>
|
||
|
<a href="poifs/index.html"><font size="-1">POIFS</font></a>
|
||
|
</li>
|
||
|
<li>
|
||
|
<a href="hssf/index.html"><font size="-1">HSSF</font></a>
|
||
|
</li>
|
||
|
<li>
|
||
|
<a href="hdf/index.html"><font size="-1">HDF</font></a>
|
||
|
</li>
|
||
|
<li>
|
||
|
<a href="utils/index.html"><font size="-1">POI-Utils</font></a>
|
||
|
</li>
|
||
|
</ul>
|
||
|
</font>
|
||
|
<br>
|
||
|
<font size="+1" color="#000000">References</font><font size="-1">
|
||
|
<ul>
|
||
|
<li>
|
||
|
<a href="livesites.html"><font size="-1">Live Sites</font></a>
|
||
|
</li>
|
||
|
<li>
|
||
|
<a href="building.xml"><font size="-1">Building</font></a>
|
||
|
</li>
|
||
|
<li>
|
||
|
<a href="http://sc.openoffice.org/excelfileformat.pdf"><font size="-1">XLS spec [PDF]</font></a>
|
||
|
</li>
|
||
|
<li>
|
||
|
<a href="http://xml.apache.org/cocoon/"><font size="-1">Apache Cocoon</font></a>
|
||
|
</li>
|
||
|
</ul>
|
||
|
</font>
|
||
|
<br>
|
||
|
<font size="+1" color="#000000">Get Involved</font><font size="-1">
|
||
|
<ul>
|
||
|
<li>
|
||
|
<a href="contrib.html"><font size="-1">Contributing</font></a>
|
||
|
</li>
|
||
|
<li>
|
||
|
<a href="https://sourceforge.net/tracker/?atid=406288&group_id=32701&func=browse"><font size="-1">Bug Database</font></a>
|
||
|
</li>
|
||
|
<li>
|
||
|
<a href="http://jakarta.apache.org/site/cvsindex.html"><font size="-1">CVS</font></a>
|
||
|
</li>
|
||
|
<li>
|
||
|
<a href="http://jakarta.apache.org/site/mail.html"><font size="-1">Mail Lists</font></a>
|
||
|
</li>
|
||
|
</ul>
|
||
|
</font>
|
||
|
<br>
|
||
|
<br>
|
||
|
</font></td><td align="left" valign="top" width="*">
|
||
|
<title>Contribution to POI</title>
|
||
|
<center>
|
||
|
<table width="80%">
|
||
|
<tr>
|
||
|
<td bgcolor="#F3DD61"><font face="Arial,sans-serif" size="+1">
|
||
|
<center>
|
||
|
<b>Contribution to POI</b>
|
||
|
</center>
|
||
|
</font></td>
|
||
|
</tr>
|
||
|
</table>
|
||
|
</center>
|
||
|
<font size="-2" color="#000000">
|
||
|
<p>
|
||
|
<a href="mailto:"></a>
|
||
|
</p>
|
||
|
</font>
|
||
|
<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>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 cellpadding="0" cellspacing="0" border="0" width="100%">
|
||
|
<tr>
|
||
|
<td>
|
||
|
<hr size="1" noshade="">
|
||
|
</td>
|
||
|
</tr>
|
||
|
<tr>
|
||
|
<td align="center"><font color="#525D76" size="-1" face="arial,helvetica,sanserif"><i>
|
||
|
Copyright ©2002 Apache Software Foundation
|
||
|
</i></font></td><td width="5%" align="right"><img src="images/cocoon2-small.jpg" align="right" border="0" vspace="0" hspace="0"></td>
|
||
|
</tr>
|
||
|
</table>
|
||
|
</body>
|
||
|
</html>
|