acoliver 2002/06/09 13:30:34
Modified: src/documentation/xdocs book.xml
src/documentation/xdocs/getinvolved index.xml
Log:
first go at "getting involved"
Revision Changes Path
1.18 +1 -0 jakarta-poi/src/documentation/xdocs/book.xml
Index: book.xml
===================================================================
RCS file: /home/cvs/jakarta-poi/src/documentation/xdocs/book.xml,v
retrieving revision 1.17
retrieving revision 1.18
diff -u -r1.17 -r1.18
--- book.xml 28 Apr 2002 21:25:28 -0000 1.17
+++ book.xml 9 Jun 2002 20:30:34 -0000 1.18
@@ -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"/>
1.2 +85 -260 jakarta-poi/src/documentation/xdocs/getinvolved/index.xml
Index: index.xml
===================================================================
RCS file: /home/cvs/jakarta-poi/src/documentation/xdocs/getinvolved/index.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- index.xml 28 Apr 2002 21:25:28 -0000 1.1
+++ index.xml 9 Jun 2002 20:30:34 -0000 1.2
@@ -5,8 +5,6 @@
<header>
<title>Contribution to POI</title>
<authors>
- <person name="Robin Green" email="[EMAIL PROTECTED]"/>
- <person name="Stefano Mazzocchi" email="[EMAIL PROTECTED]"/>
<person name="Nicola Ken Barozzi" email="[EMAIL PROTECTED]"/>
<person name="Marc Johnson" email="[EMAIL PROTECTED]"/>
<person name="Andrew C. Oliver" email="[EMAIL PROTECTED]"/>
@@ -16,264 +14,91 @@
<body>
<section title="Introduction">
-
- <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. ...).
- </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">
- <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:
- </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
- <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>
- </ul>
- </section>
-
- <anchor id="procedure"/>
- <section title="Procedure for Raising Development Issues">
- <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.
- </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.
- </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.
- </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 title="Disclaimer">
+ <p>
+ 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>
+ </section>
+ <section title="The Licenseing">
+ <p>
+ 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>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>
+ <section title="Submitting Patches">
+ <p>
+ 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>
+ 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>
+ 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>
+ </section>
</body>
</document>
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
