- The POI Project is an Open Source - 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. ...). -
-- To begin with, we suggest you subscribe to the - POI mailing lists - (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. -
- -You can get your local working copy of the - latest and - greatest code (which you find in the jakarta-poi module in - the CVS code repository. Review the todo 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.) -
- -- 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! -
- -- 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: -
-users
mailing list - there is often a problem of
- having too many questioners and not enough experts to respond to all the questions.general POI mailing list
- , install and try out POI
- and read some of the mail archives.
- 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!).zip
and
- .tar.gz
packages, but anyone is welcome to build their own specific packages and
- announce them on the general POI list
)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. -
- -
- (Further general CVS usage information is at
- www.cvshome.org and your local
- info cvs
pages or man cvs
pages or user
- documentation.)
-
- 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.) -
-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. -
- -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. -
- -
- 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
- developer
mailing list
- and the bug database.
-
- 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. -
- -
- Most issues will be discovered, resolved, and then patched quickly
- via the developer
mailing list. Larger issues, and ones that
- are not yet fully understood or are hard to solve, are destined for
- Bugzilla.
-
- 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. -
- -
- As a rule-of-thumb, discuss an issue on the developers
- 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.
-
- 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. -
-- This is a collection of tips for contributing to the project in a manner - that is productive for all parties. -
- -In-reply-to
header). Otherwise, your new topic will get
- lost in the previous thread and go un-answered.
- [Patch]
, [Proposal]
,
- [RT]
(Random Thought, these quickly blossom into research
- topics :-), [STATUS]
(development status of a certain
- feature).
- build docs
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
- jEdit. For
- his XML editing. (That is when he's not hacking it in 'vi' the true editor
- and light of the text editing world!).
- + 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. +
++ The POI project is OpenSource + and developed/distributed under the + Apache Software License. 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. +
++ 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. +
++ 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) +
++ 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. +
++ 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. +
++ Patches are submitted via the Bug Database. + 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?). +
++ 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 + Coding + Standards). Patches that are of low quality may be rejected or + the contributer may be asked to bring them up to spec. +
+