From 3899a5ee12ee3dc10e0e2f5410d6337d8ac8388c Mon Sep 17 00:00:00 2001 From: "Andrew C. Oliver" Date: Sun, 9 Jun 2002 20:30:34 +0000 Subject: [PATCH] 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 --- src/documentation/xdocs/book.xml | 1 + src/documentation/xdocs/getinvolved/index.xml | 343 +++++------------- 2 files changed, 85 insertions(+), 259 deletions(-) diff --git a/src/documentation/xdocs/book.xml b/src/documentation/xdocs/book.xml index e4cfc0a1d..a0f0a40d6 100644 --- a/src/documentation/xdocs/book.xml +++ b/src/documentation/xdocs/book.xml @@ -10,6 +10,7 @@ + diff --git a/src/documentation/xdocs/getinvolved/index.xml b/src/documentation/xdocs/getinvolved/index.xml index e95bc34b1..15729f045 100644 --- a/src/documentation/xdocs/getinvolved/index.xml +++ b/src/documentation/xdocs/getinvolved/index.xml @@ -5,8 +5,6 @@
Contribution to POI - - @@ -16,264 +14,91 @@
- -

- 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: -

-
    -
  • Answering questions on the users mailing list - there is often a problem of - having too many questioners and not enough experts to respond to all the questions.
    • -
  • Testing POI (especially its less-frequently-used features) on various configurations - and reporting back.
    • -
  • Debugging - producing reproducible test cases and/or finding causes of bugs. Some known bugs are informally listed on - To Do, and some are recorded in Bugzilla - (see explanation below).
    • -
  • Specifying/analyzing/designing new features - and beyond. (If you wish to get involved - with this, please join the 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!)
    • -
  • 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 .zip and - .tar.gz packages, but anyone is welcome to build their own specific packages and - announce them on the general POI list)
    • -
  • ... 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. -
    • -
- -
- - -
-

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. -

- -
    -
  • The CVS Book
    • -
  • www.cvshome.org
    • -
  • - - 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.
    • -
-
- - -
-

- 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. -

- -
    -
  • - Every contribution is worthwhile. Even if the ensuing discussion - proves it to be off-beam, then it may jog ideas for other people. -
    • -
  • - Use sensible and concise email subject headings. Search engines, and - humans trying to browse a voluminous list, will respond favorably to a - descriptive title. -
    • -
  • Start new threads with new Subjects for new topics, rather than - re-using the previous Subject line. -
    • -
  • Keep each topic focussed. If some new topic arises, start a new - discussion. This leaves the original topic to continue un-cluttered. -
    • -
  • 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 - In-reply-to header). Otherwise, your new topic will get - lost in the previous thread and go un-answered. -
    • -
  • - Prepend your email subject line with a marker when that is appropriate, - e.g. [Patch], [Proposal], - [RT] (Random Thought, these quickly blossom into research - topics :-), [STATUS] (development status of a certain - feature). -
    • -
  • - When making changes to XML documentation, or any XML document for that - matter, use a - validating parser - (one that is tried and true is - SP/nsgmls). - This procedure will detect errors without having to go through the whole - 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!). -
    • -
  • - 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. -
    • -
  • - 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. -
    • -
  • - Try to at least offer a partial solution and not just a problem statement. -
    • -
  • - Take the time to clearly explain your issue and write a concise email - message. Less confusion facilitates fast and complete resolution. -
    • -
  • - 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. -
    • -
  • - You would usually do any development work against the HEAD branch of CVS. -
    • -
  • - 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. -
    • -
  • - 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. -
    • -
  • - Become familiar with the mailing lists. As you browse and search, you will - see the way other people do things. Follow the leading examples. -
    • -
+
+

+ 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. +

+
+
+
    +
  • Read the rest of the website, understand what POI is and what it does, + the project vision, etc.
    • +
  • Use POI a bit, look for gaps in the documentation and examples.
    • +
  • Join the mail lists and share your knowledge with others.
    • +
  • Get CVS and check out the POI source tree
    • +
  • 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.
    • +
  • Get used to building POI, you'll be doing it a lot, be one with the build, know its targets, etc.
    • +
  • 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.
    • +
  • (HSSF)Get the Excel 97 Developer's Kit - its out of print but its dirt cheap (seen copies for under $15 (US)) used on amazon. It explains the Excel file format.
    • +
  • Submit patches (see below) of your contributions, modifications.
    • +
  • Fill out new features, see Bug database for suggestions.
    • +
+
+
+

+ 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. +

+