moparisthebest/poi
1
0
Fork 0
Code Issues Pull Requests Releases 1 Wiki Activity

first go at "getting involved"

Browse Source 
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 2002-06-09 20:30:34 +00:00
parent d3ad81d4e7
commit 3899a5ee12
2 changed files with 85 additions and 259 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
src/documentation/xdocs/book.xml
View File

@ -10,6 +10,7 @@
<menu-item label="News" href="news.html"/>
<menu-item label="Changes" href="changes.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="History and Future" href="historyandfuture.html"/>
<menu-item label="Who we are" href="who.html"/>

315
src/documentation/xdocs/getinvolved/index.xml
View File

@ -5,8 +5,6 @@
<header>
<title>Contribution to POI</title>
<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="Marc Johnson" email="mjohnson@apache.org"/>
<person name="Andrew C. Oliver" email="acoliver@apache.org"/>
@ -16,263 +14,90 @@
<body>
<section title="Introduction">
<section title="Disclaimer">
<p>
The POI Project is an <link href="http://www.opensource.org/">Open Source</link>
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. ...).
Any information in here that might be percieved as legal information is
informational only. We're not lawyers, so consult a legal professional
if needed.
</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 title="Help Wanted Here">
<section title="The Licenseing">
<p>
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:
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">
<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>
<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
<link href="todo.html">To Do</link>, and some are recorded in Bugzilla
(see <link href="#procedure">explanation below</link>).</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 <link href="mail-lists.html">mail archives</link>.
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>
<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="http://jakarta.apache.org/site/cvsindex.html">CVS</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://jakarta.apache.org/site/bugs.html">Bug database</link> for suggestions.</li>
</ul>
</section>
<anchor id="procedure"/>
<section title="Procedure for Raising Development Issues">
<section title="Submitting Patches">
<p>
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> <link href="mail-lists.html">mailing list</link>
and the bug database.
Create patches by getting the latest sources from CVS (the HEAD).
Alter or add files as appropriate. Then, from the jakarta-poi directiory,
type cvs diff -u > 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 jakarta-poi directory.
You'll attach both files in the next step.
</p>
<p>
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.
Patches are submitted via the <link href="http://jakarta.apache.org/site/bugs.html">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>
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.
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://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>
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 &quot;Reply to&quot; 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>
</body>