cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject [DAISY] Created: Contribution to Apache Cocoon
Date Mon, 31 Jul 2006 16:03:53 GMT
A new document has been created.

Document ID: 1177
Branch: main
Language: default
Name: Contribution to Apache Cocoon
Document Type: Cocoon Document
Created: 7/31/06 4:03:45 PM
Creator (owner): Helma van der Linden
State: publish


Mime type: text/xml
Size: 18512 bytes


<p>The Apache Cocoon Project is an <a href="">Open
Source</a> volunteer project under the auspices of the
<a href="">Apache Software Foundation (ASF)</a>, and, in
harmony with the Apache webserver itself, it is released under a very open
<a href="">license</a>. 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 to subscribe to the
<a href="daisy:1175">Cocoon mailing lists</a> (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.</p>

<p>You can get your local working copy of the
<a href="">current
release branch</a>, or the
<a href="">latest development
branch</a> from Subversion (SVN). Review the
<a href="">todo</a> 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.)</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!</p>

<h1>Help Wanted Here</h1>

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

<li>Answering questions on the <tt>cocoon-users</tt> mailing list - there
often a problem of having too many questioners and not enough experts to respond
to all the questions.</li>
<li>Testing Cocoon (especially its less-frequently-used features) on various
configurations and reporting back.</li>
<li>Debugging - producing reproduceable test cases and/or finding causes of
bugs. Some known bugs are informally listed on
<a href="">To Do</a>, and some are
recorded in JIRA (see <a href="#procedure">explanation below</a> [[NOTE: link
<li>Specifying/analysing/designing new features for Cocoon - and beyond. (If you
wish to get involved with this, please join <tt></tt> (you
may also want to join <tt></tt>), install and try out
Cocoon and read some of the <a href="daisy:1175">mail archives</a>. 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
<li>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 <tt>.zip</tt> and <tt>.tar.gz</tt> packages, but anyone is welcome
build their own specific packages and announce them on <tt>cocoon-users</tt>)
<li>... 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.</li>

<p>Thank you very much.</p>

<h1 id="contrib">Contributions of Code and Documentation</h1>

<p>If you have a contribution that you would like to see incorporated into the
Cocoon distribution, then please take note of the <a href="#license">licensing
requirements</a> listed below, and then read the section
<a href="#procedure">Procedure for Raising Development Issues</a>.</p>

<p>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, JIRA.</p>

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

<h2>Testing Requirements for Cocoon Contrib and Distribution</h2>

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

<li>Apache Tomcat 3.2.2</li>

<p>It should also be tested on the following platforms:</p>

<li>A Windows operating system</li>
<li>A UNIX-type operating system</li>
<li>At least JDK version 1.3.x</li>

<p>And obviously, it should be tested using the current Cocoon source code!</p>

<p>This testing is designed to iron out the most common kinds of incompatibility
problems (Servlet &gt;2.2 requirements; platform-dependent assumptions; JDK
&gt;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!</p>

<h2>Documentation Requirements for Cocoon Distribution</h2>

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

<p class="fixme">This should be done using
<a href="">Daisy</a>. [[NOTE: add more info

<h2 id="license">Licensing Requirements for the Cocoon Distribution</h2>

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

<li>Source code files (which include every file, code and documentation) must be
under the <a href="">Apache license</a>. and must
have copyright assigned to the Apache Software Foundation.</li>
<li>Jar files need to be released under a license that permits free
redistribution (i.e. not any more restrictive than the Apache License). So for
example, the GPL and LGPL are not allowed, but MPL and Apache licenses are

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

<h1>Subversion Usage Precis</h1>

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

<p>(Further general Subversion usage information is at
<a href=""></a>. Other
resources include <a href="">"Version Control with
Subversion"</a> and
<a href="">a
fast introduction</a>.</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>

<h2>How to Establish your Local Repository</h2>

<p>Decide whether you want to work with the "release branch" (2.1.X) or with the
trunk (2.2). Some developers use both.</p>

<p>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 <tt>BRANCH_2_1_X</tt></p>

<li><tt>cd /usr/local/svn/cocoon</tt></li>
<li><tt>svn co</tt></li>
<li><tt>cd BRANCH_2_1_X</tt></li>

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

<h2>How to Keep it Up-to-date</h2>

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

<li><tt>cd /usr/local/svn/cocoon/BRANCH_2_1_X</tt></li>
<li><tt>svn update</tt></li>
<li><strong>... pay attention to the update messages</strong></li>

<h2>How to Generate Differences</h2>

<p>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 <tt>cocoon-dev</tt> mailing list. One of the authorised
maintainers of the repository will review the patch and then apply it to the
relevant branch.</p>

<p>We will assume that you are adding some tips to this document

<li>Make the desired changes in your local repository, build, test it thoroughly
<li><tt>cd /usr/local/svn/cocoon/BRANCH_2_1_X/xdocs</tt></li>
<li><tt>svn diff contrib.xml &gt; $WORK/cocoon/contrib.xml.diff</tt></li>

<h2>How to get other branches</h2>

<p>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
<a href=""></a>
Then follow the same checkout procedure described above, using this ...</p>

<li><tt>cd /usr/local/svn/cocoon</tt></li>
<li><tt>svn co</tt>

<p>If you want to work with the trunk, then do this to create a local directory
called "cocoon-trunk" ...</p>

<li><tt>cd /usr/local/svn/cocoon</tt></li>
<li><tt>svn co cocoon-trunk</tt>

<h1>Committer repository access</h1>

<p>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 and run <tt>svnpasswd username</tt>. This will ask you for
subversion password. This is the user and password you can use when checking in
code. See also <a href="">ASF
developer notes</a> about version control.</p>

<h1 id="procedure">Procedure for Raising Development Issues</h1>

<p>Documentation contributions can usually be added directly to the issue
tracker. First read the <a href="#contrib">contribution notes</a> above, then
follow the <a href="daisy:619#contribution">howto documents</a> about patching
and about using JIRA.</p>

<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 <tt>cocoon-dev</tt>
<a href="daisy:1175">mailing list</a> and when to use
<a href="">JIRA</a> (the Apache Bug

<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
<tt>cocoon-dev</tt> mailing list. Larger issues, and ones that are not yet fully
understood or are hard to solve, are destined for JIRA.</p>

<p>Experienced developers use JIRA 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 JIRA without caring if it is a bug of Cocoon
or their own installation/configuration mistake - please do not do this.</p>

<p>As a rule-of-thumb, discuss an issue on the <tt>cocoon-dev</tt> mailing
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 JIRA.</p>

<p>When you are sure about your proposed patch, then please submit it
<a href="">via
JIRA</a>, rather than as email to <tt>cocoon-dev</tt>. Be sure to add [PATCH]
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

<p>When posting discussion topics to the <tt>cocoon-dev</tt> list, then
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.</p>

<h1>Contribution Notes and Tips</h1>

<p>This is a collection of tips for contributing to the project in a manner that
is productive for all parties.</p>

<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 favourably to a descriptive
<li>See <a href="daisy:1175">Tips</a> for Cocoon mailing lists and
<a href="">Message Editing and Quoting Guide (with
<li>Start new threads with new Subject for new topics, rather than re-using the
previous Subject line.</li>
<li>Keep each topic focussed. If some new topic arises then 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 utilise the <tt>In-reply-to</tt> header). If so, then 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.
<tt>[Vote]</tt>, <tt>[Proposal]</tt>, <tt>[RT]</tt> (Random
Thought which
quickly blossom into research topics :-), <tt>[STATUS]</tt> (development status
of a certain facility).</li>
<li>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.</li>
<li>When making changes to XML documentation, or any XML document for that
matter, use a <a href="">validating parser</a>
(one that is tried and true is
<a href="">OpenSP/onsgmls</a>). This procedure
will detect errors without having to go through the whole <tt>build docs</tt>
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.)</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>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>When sending a patch, you usually do not need to worry about which branch it
should be applied to. The maintainers of the repository will decide and might
also apply it to the trunk. Please indicate on the Bugzilla entry which branch
you have used to prepare your patch.</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 finalise 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>


The document belongs to the following collections: generaldocs

View raw message