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 current release branch, or the latest development branch from Subversion (SVN). 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:
Thank you very much.
If you have a contribution that you would like to see incorporated into the Cocoon distribution, then please take note of the licensing requirements listed below, and then read the section Procedure for Raising Development Issues.
The Cocoon committers have been granted access by a vote of confidence, so they are assumed to be trustworthy enough to make changes directly in the source repository. Other contributors need to submit a patch via the Cocoon issue tracker, Bugzilla.
Committers must be confident that it would work properly in all operating systems, it must be documented as appropriate, it must be considered sufficiently useful and general to go into Cocoon, and it must meet the Licensing requirements below. Other committers and developers will continue to enhance it, so don't be surprised if changes are made. Also the PMC may decide to remove it, if issues are discovered.
All new code should be tested under at least the following servlet engines:
It should also be tested on the following platforms:
And obviously, it should be tested using the current Cocoon source code!
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:
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!
An overview of how to use Subversion 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 Subversion usage information is at subversion.tigris.org. Other resources include "Version Control with Subversion" and a fast introduction.
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.)
Decide whether you want to work with the "release branch" (2.1.X) or with the trunk (2.2). Some developers use both.
The following procedure will checkout the current copy of the release branch of the master repository and download it to your local disk. It will create a sub-directory called BRANCH_2_1_X
You now have the release branch of the current source 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 ...
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
Okay, that got the current release branch of Cocoon into your local working copy. If you want some other branch, then find the relevant branch name from ViewCVS http://svn.apache.org/viewcvs.cgi/cocoon/ Then follow the same checkout procedure described above, using this ...
If you want to work with the trunk, then do this to create a local directory called "cocoon-trunk" ...
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 the repository. To be able to commit you will first need to generate a subversion password. To do this, ssh to minotaur.apache.org and run svnpasswd username. This will ask you for a subversion password. This is the user and password you can use when checking in code. See also ASF developer notes about version control.
Documentation contributions can usually be added directly to the issue tracker. First read the contribution notes above, then follow the howto documents about patching and about using Bugzilla.
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.