moparisthebest
/
poi
1
0
Fork 0
Code Issues Pull Requests Releases 1 Wiki Activity
poi/build/jakarta-poi/docs/contrib.html

531 lines
17 KiB
HTML
Raw Permalink Blame History

<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 &gt;</a><a class="black" href="http://jakarta.apache.org/">jakarta.apache.org &gt;</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://sourceforge.net/project/showfiles.php?group_id=32701">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>
<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 &copy; 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>
Reference in New Issue View Git Blame Copy Permalink