mirror of https://github.com/apache/poi.git
first go at "getting involved"
PR: Obtained from: Submitted by: Reviewed by: git-svn-id: https://svn.apache.org/repos/asf/jakarta/poi/trunk@352667 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Andrew C. Oliver
parent
f3898b543e
commit
1ee094bef2
|
|
@ -10,6 +10,7 @@
|
||||||
<menu-item label="News" href="news.html"/>
|
<menu-item label="News" href="news.html"/>
|
||||||
<menu-item label="Changes" href="changes.html"/>
|
<menu-item label="Changes" href="changes.html"/>
|
||||||
<menu-item label="To do" href="todo.html"/>
|
<menu-item label="To do" href="todo.html"/>
|
||||||
|
<menu-item label="Get Involved" href="getinvolved/index.html"/>
|
||||||
<menu-item label="Vision" href="plan/POI20Vision.html"/>
|
<menu-item label="Vision" href="plan/POI20Vision.html"/>
|
||||||
<menu-item label="History and Future" href="historyandfuture.html"/>
|
<menu-item label="History and Future" href="historyandfuture.html"/>
|
||||||
<menu-item label="Who we are" href="who.html"/>
|
<menu-item label="Who we are" href="who.html"/>
|
||||||
|
|
|
||||||
|
|
@ -5,8 +5,6 @@
|
||||||
<header>
|
<header>
|
||||||
<title>Contribution to POI</title>
|
<title>Contribution to POI</title>
|
||||||
<authors>
|
<authors>
|
||||||
<person name="Robin Green" email="greenrd@hotmail.com"/>
|
|
||||||
<person name="Stefano Mazzocchi" email="stefano@apache.org"/>
|
|
||||||
<person name="Nicola Ken Barozzi" email="barozzi@nicolaken.com"/>
|
<person name="Nicola Ken Barozzi" email="barozzi@nicolaken.com"/>
|
||||||
<person name="Marc Johnson" email="mjohnson@apache.org"/>
|
<person name="Marc Johnson" email="mjohnson@apache.org"/>
|
||||||
<person name="Andrew C. Oliver" email="acoliver@apache.org"/>
|
<person name="Andrew C. Oliver" email="acoliver@apache.org"/>
|
||||||
|
|
@ -16,263 +14,90 @@
|
||||||
<body>
|
<body>
|
||||||
|
|
||||||
<section title="Introduction">
|
<section title="Introduction">
|
||||||
|
<section title="Disclaimer">
|
||||||
<p>
|
<p>
|
||||||
The POI Project is an <link href="http://www.opensource.org/">Open Source</link>
|
Any information in here that might be percieved as legal information is
|
||||||
volunteer project released under a very open license.
|
informational only. We're not lawyers, so consult a legal professional
|
||||||
This means there are many ways to contribute to the project - either
|
if needed.
|
||||||
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>
|
||||||
<p>
|
|
||||||
To begin with, we suggest you subscribe to the
|
|
||||||
<link href="mail-lists.html">POI mailing lists</link>
|
|
||||||
(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>You can get your local working copy of the
|
|
||||||
<link href="http://jakarta.apache.org/site/cvsindex.html">latest and
|
|
||||||
greatest code</link> (which you find in the jakarta-poi module in
|
|
||||||
the CVS code repository. Review the <link href="todo.html">todo</link> 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>
|
|
||||||
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>
|
|
||||||
|
|
||||||
</section>
|
</section>
|
||||||
|
<section title="The Licenseing">
|
||||||
<section title="Help Wanted Here">
|
|
||||||
<p>
|
<p>
|
||||||
The rest of this document is mainly about
|
The POI project is <link href="http://www.opensource.org">OpenSource</link>
|
||||||
contributing new or improved code and/or documentation, but we would also be glad to have
|
and developed/distributed under the <link
|
||||||
extra help in any of the following areas:
|
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>
|
</p>
|
||||||
|
</section>
|
||||||
|
<section title="I just signed an NDA to get a spec from Microsoft and I'd like to contribute">
|
||||||
|
<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) recieved such information from a person bound by
|
||||||
|
such an agreement, you cannot participate in this project. (Sorry)
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
Those submitting patches that show incite 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">
|
||||||
<ul>
|
<ul>
|
||||||
<li>Answering questions on the <code>users</code> mailing list - there is often a problem of
|
<li>Read the rest of the website, understand what POI is and what it does,
|
||||||
having too many questioners and not enough experts to respond to all the questions.</li>
|
the project vision, etc.</li>
|
||||||
<li>Testing POI (especially its less-frequently-used features) on various configurations
|
<li>Use POI a bit, look for gaps in the documentation and examples.</li>
|
||||||
and reporting back.</li>
|
<li>Join the mail lists and share your knowledge with others.</li>
|
||||||
<li>Debugging - producing reproducible test cases and/or finding causes of bugs. Some known bugs are informally listed on
|
<li>Get <link href="http://jakarta.apache.org/site/cvsindex.html">CVS</link> and check out the POI source tree</li>
|
||||||
<link href="todo.html">To Do</link>, and some are recorded in Bugzilla
|
<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>
|
||||||
(see <link href="#procedure">explanation below</link>).</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>Specifying/analyzing/designing new features - and beyond. (If you wish to get involved
|
<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>
|
||||||
with this, please join the <code>general POI mailing list</code>
|
<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>
|
||||||
, install and try out POI
|
<li>Submit patches (see below) of your contributions, modifications.</li>
|
||||||
and read some of the <link href="mail-lists.html">mail archives</link>.
|
<li>Fill out new features, see <link href="http://jakarta.apache.org/site/bugs.html">Bug database</link> for suggestions.</li>
|
||||||
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>
|
|
||||||
|
|
||||||
</section>
|
|
||||||
|
|
||||||
<anchor id="cvshowto"/>
|
|
||||||
<section title="CVS Usage Precis">
|
|
||||||
<p>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>
|
|
||||||
(Further general CVS usage information is at
|
|
||||||
<link href="http://www.cvshome.org/">www.cvshome.org</link> and your local
|
|
||||||
<code>info cvs</code> pages or <code>man cvs</code> pages or user
|
|
||||||
documentation.)
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p>
|
|
||||||
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>
|
|
||||||
</section>
|
|
||||||
<anchor id="ssh"/>
|
|
||||||
<section title="CVS Committer with Secure Shell access">
|
|
||||||
<p>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>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><link href="http://cvsbook.red-bean.com/">The CVS Book</link></li>
|
|
||||||
<li><link href="http://www.cvshome.org/">www.cvshome.org</link></li>
|
|
||||||
<li><link href="https://sourceforge.net/cvs/?group_id=32701"></link>
|
|
||||||
- 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>
|
</ul>
|
||||||
</section>
|
</section>
|
||||||
|
<section title="Submitting Patches">
|
||||||
<anchor id="procedure"/>
|
|
||||||
<section title="Procedure for Raising Development Issues">
|
|
||||||
<p>
|
<p>
|
||||||
There are two methods for discussing development and submitting patches.
|
Create patches by getting the latest sources from CVS (the HEAD).
|
||||||
So that everyone can be productive, it is important to know which method
|
Alter or add files as appropriate. Then, from the jakarta-poi directiory,
|
||||||
is appropriate for a certain situation and how to go about it without
|
type cvs diff -u > mypatch.patch. This will capture all of your changes
|
||||||
confusion. This section explains when to use the
|
in a patch file of the appropriate format. Next, if you've added any
|
||||||
<code>developer</code> <link href="mail-lists.html">mailing list</link>
|
files, create an archive (tar.bz2 preferred as its the smallest) in a
|
||||||
and the bug database.
|
path-preserving archive format, relative to your jakarta-poi directory.
|
||||||
|
You'll attach both files in the next step.
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
Research your topic thoroughly before beginning to discuss a new
|
Patches are submitted via the <link href="http://jakarta.apache.org/site/bugs.html">Bug Database</link>.
|
||||||
development issue. Search and browse through the email archives - your
|
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.
|
||||||
issue may have been discussed before. Prepare your post clearly and
|
Next, go back to the bug, and create attachements for the patch files you
|
||||||
concisely.
|
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>
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
Most issues will be discovered, resolved, and then patched quickly
|
Make sure your patches include the @author tag on any files you've altered
|
||||||
via the <code>developer</code> mailing list. Larger issues, and ones that
|
or created. Make sure you've documented your changes and altered the
|
||||||
are not yet fully understood or are hard to solve, are destined for
|
examples/etc to reflect them. Any new additions should have unit tests.
|
||||||
Bugzilla.
|
Lastly, ensure that you've provided approriate javadoc. (see
|
||||||
|
<link href="http://jakarta.apache.org/poi/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>
|
</p>
|
||||||
|
|
||||||
<p>
|
|
||||||
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>
|
|
||||||
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>
|
|
||||||
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>
|
|
||||||
</section>
|
|
||||||
|
|
||||||
<anchor id="tips"/>
|
|
||||||
<section title="Contribution Notes and Tips">
|
|
||||||
<p>
|
|
||||||
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
|
|
||||||
<link href="http://www.oasis-open.org/cover/">validating parser</link>
|
|
||||||
(one that is tried and true is
|
|
||||||
<link href="http://www.jclark.com/sp/">SP/nsgmls</link>).
|
|
||||||
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
|
|
||||||
<link href="http://www.sourceforge.net/projects/jedit">jEdit</link>. 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>
|
|
||||||
</section>
|
</section>
|
||||||
|
|
||||||
</body>
|
</body>
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue