The Apache Cocoon Project is an Open Source volunteer project under the auspices of the Apache Software Foundation (ASF), and, in harmony with the Apache webserver itself, it is 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 to subscribe to the Cocoon 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 contibutions.

You can get your local working copy of the latest and greatest code (which you find in the xml-cocoon2 module in the cvs.apache.org CVS code repository, or from the CVS snapshots). Review the todo list, choose a task (or perhaps you have noticed something that needs patching). Make the changes, do the testing, generate a patch, if you need then discuss it on the cocoon-dev mailing list, and add the patch to Bugzilla. (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!

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 cocoon-users mailing list - there is often a problem of having too many questioners and not enough experts to respond to all the questions.
• Testing Cocoon (especially its less-frequently-used features) on various configurations and reporting back.
• Debugging - producing reproduceable 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/analysing/designing new features for Cocoon - and beyond. (If you wish to get involved with this, please join [email protected] (you may also want to join [email protected]), install and try out Cocoon and read some of the mail archives. You should have a strong "fluency" in XML technologies, Java and a basic understanding of the Cocoon 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 Cocoon 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 cocoon-users)
• ... and there is just one other thing - don't forget to tell everyone who asks, how great Cocoon is! ;-) The more people that know about and start to use Cocoon, the larger the pool of potential contributors there will be - so, please, help us by placing the Cocoon logo somewhere in your site to indicate that you are using and supporting the Cocoon Project.

Thank you very much.

We are starting to use an informal system for accepting contributions to Cocoon. The process varies depending on whether the contribution is a modification (i.e. patch) or a fairly standalone item, and whether you have commit access (committers have been granted access by a vote of confidence, so they are assumed to be trustworthy enough to make changes directly in CVS. If you submit many good patches, you may be nominated as a committer yourself!)

If your contribution requires changing more than a few lines of Cocoon (code or documentation), then it counts as a patch. If you have a patch and would like to see it incorporated into the Cocoon distribution, take note of the Licensing Requirements listed below, and then read the section Procedure for Raising Development Issues

A typical contribution (not a patch) may go through the following stages:

1. Posted to cocoon-users with a URL to download it from.
2. Inclusion into the contrib directory, which is for 3rd-party contributions that have been tested, but are not necessarily mature enough or general enough for the main distribution. [Must be tested at least as specified below. See also Licensing Requirements below.]
3. Inclusion into the main distribution. [Committers must be confident that it should work properly in most/all environments, it must be documented as appropriate, and it must be considered sufficiently useful and general to go into Cocoon. See also Licensing Requirements below].

All new code should be tested under at least the following servlet engines:

• Apache Tomcat 3.2.2

It should also be tested on the following platforms:

• A Windows operating system
• A UNIX-type operating system
• At least JDK version 1.2.x

And obviously, it should be tested against the current CVS snapshot of Cocoon!

This testing is designed to iron out the most common kinds of incompatibility problems (Servlet >2.2 requirements; platform-dependent assumptions; JDK >1.2 code). These requirements are, of course, open to review and discussion. Note that the contributor is not required to do the testing - indeed it is probably better if someone else tests it, because the contributor might be tempted to do less than thorough testing!

All new features (processor, logicsheets, config options etc.) should be documented appropriately (in XML or in cocoon.xconf in the case of config options).

Use something like xdocs/contrib.xml as a rough guide, add the new page(s) to xdocs/book.xml to create the menu-link and type build.sh docs or build.bat docs to test the documentation build.

To avoid legal problems, the Apache Project Management Committee (PMC) have agreed on a policy for under what licensing code can be accepted into Apache projects:

• Source code files must be under the Apache license and must have copyright assigned to the Apache Software Foundation.
• Jar files need only be released under a license that permits free redistribution and does not cover new files added to the jar/library (so the GPL and LGPL are not allowed, but MPL and Apache licenses are, for example).

By submitting a patch, you signify your understanding and acceptance of these conditions - like most open source projects, we do not have the resources nor the inclination to obtain signed statements from all contributors!

Note: Since the contrib/ directory of Cocoon CVS contains third-party. completely optional extensions, one of the above requirements is relaxed. Code in the contrib directory does not have to have its copyright assigned to the ASF - but it must still be released under the Apache license.

An overview of how to use CVS to participate in Cocoon 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. Therefore, 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.)

This will checkout the current copy of the master cvs repository and download it to your local disk. It will create a sub-directory called xml-cocoon2

1. cd /usr/local/cvs
2. cvs -d :pserver:[email protected]:/home/cvspublic login
3. ... use this password: anoncvs
4. cvs -d :pserver:[email protected]:/home/cvspublic checkout xml-cocoon2
5. cvs -d :pserver:[email protected]:/home/cvspublic logout
6. cd xml-cocoon2

You now have the HEAD branch of the current development cvs repository for Cocoon on your local system. Go ahead and build and deploy as usual. Make some changes, re-build, and see the effect.

Every so often you should synchronise your local copy with the master repository. Note that this definitely does not mean that your changes will be applied to the master. Exactly the opposite will happen - updates from the remote master version are merged into your local repository. New items are automatically added to yours, and changed ones are refreshed. If someone else happened to have submitted patches for the same files while you were away, then changes will be merged with your copy and you will be warned of any conflicts. Easy and automatic ...

1. cd /usr/local/cvs
2. cvs -d :pserver:[email protected]:/home/cvspublic login
3. cvs -d :pserver:[email protected]:/home/cvspublic update -d -P xml-cocoon2
4. ... pay attention to the update messages
5. cvs -d :pserver:[email protected]:/home/cvspublic logout

To contribute your modifications, you need to produce a plain-text file containing the differences between the master copy and yours. You will submit this to Bugzilla along with an explanation of why it is required, and perhaps discuss it on the cocoon-dev mailing list. One of the authorised maintainers of the repository will review the patch and then apply it to the relevant branch.

We will assume that you are adding some tips to this document xdocs/contrib.xml

1. Make the desired changes in your local repository, build, test it thoroughly
2. cd /usr/local/cvs/xml-cocoon2/xdocs
3. cvs -d :pserver:[email protected]:/home/cvspublic login
4. cvs diff -u contrib.xml > $WORK/cocoon/contrib.xml.diff
5. cvs -d :pserver:[email protected]:/home/cvspublic logout

OK that got the HEAD branch of CVS into your local working copy. If you want some other branch, then find the relevant branch name from ViewCVS http://cvs.apache.org/viewcvs.cgi/xml-cocoon2/ (see the Tags list at the bottom). Then follow the same checkout procedure described above, using this ...

• cd /usr/local/cvs/cocoon_some_branch
• cvs -d :pserver:[email protected]:/home/cvspublic checkout -r cocoon_2_0_3_branch xml-cocoon2

After a developer has consistently provided contributions (code, documentation and discussion), then the rest of the cocoon-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
• Jakarta Guide: CVS Repository - 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 cocoon-dev mailing list and when to use Bugzilla (the Apache 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 cocoon-dev 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 always enter everything into Bugzilla without caring if it is a bug of Cocoon or their own installation/configuration mistake - please do not do this.

As a rule-of-thumb, discuss an issue on the cocoon-dev 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 via Bugzilla.

When you are sure about your proposed patch, then please submit it via Bugzilla, rather than as email to cocoon-dev. Be sure to add [PATCH] to the summary line, as this enables the automatic patch alert system to keep track of it. If you do not follow this procedure, then unfortunately your patch may be over-looked.

When posting discussion topics to the cocoon-dev list, then please be patient. Perhaps you do not get any answer on your first reply, so just post it again until you get one. (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 favourably to a descriptive title.
• See Tips for Cocoon mailing lists and Message Editing and Quoting Guide (with Examples).
• Start new threads with new Subject for new topics, rather than re-using the previous Subject line.
• Keep each topic focussed. If some new topic arises then 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 utilise the In-reply-to header). If so, then 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. [Vote], [Proposal], [RT] (Random Thought which quickly blossom into research topics :-), [STATUS] (development status of a certain facility).
• Please follow up with a final posting when your issue is solved. This should summarise your problem and its solution. Add [SUMMARY] to the subject line. This will ease the FAQ generation and searching of the list. Note that some people tend to ignore questions from those that never follow up.
• When making changes to XML documentation, or any XML document for that matter, use a validating parser (one that is tried and true is OpenSP/onsgmls). This procedure will detect errors without having to go through the whole build docs process to find them. Do not expect Cocoon or the build system to detect the validation errors for you - they can do it, but that is not their purpose. (Anyway, onsgmls validation error messages are more informative.)
• 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 finalise 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.