<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "document-v12.dtd">

<document>
 <header>
  <title>Contribution to Apache Cocoon</title>
  <authors>
   <person name="Robin Green" email="greenrd@hotmail.com"/>
   <person name="Stefano Mazzocchi" email="stefano@apache.org"/> 
  </authors>
 </header>

 <body>

 <section id="intro">
 <title>Introduction</title>

  <p>
   The Apache Cocoon Project is an <link href="http://www.opensource.org/">Open Source</link>
   volunteer project under the auspices of the
   <link href="http://www.apache.org/">Apache Software Foundation (ASF)</link>,
   and, in harmony with the Apache webserver itself, it is released under
   a very open 
   <link href="http://www.apache.org/licenses/">license</link>.
   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
   <link href="mail-lists.html">Cocoon mailing lists</link>
   (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
   <link href="http://svn.apache.org/viewcvs.cgi/cocoon/branches/BRANCH_2_1_X/">current release branch</link>,
   or the <link href="http://svn.apache.org/viewcvs.cgi/cocoon/trunk/">latest development branch</link>
   from Subversion (SVN). 
   Review the <link href="http://cocoon.apache.org/2.1/todo.html">todo</link> 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>
 </section>

 <section id="help">
 <title>Help Wanted Here</title>
  <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>
  <ul>
   <li>Answering questions on the <code>cocoon-users</code> mailing list - there is 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
    <link href="http://cocoon.apache.org/2.1/todo.html">To Do</link>, and some are recorded in Bugzilla
    (see <link href="#procedure">explanation below</link>).</li>
   <li>Specifying/analysing/designing new features for Cocoon - and beyond. (If you wish to get involved
    with this, please join <code>dev@cocoon.apache.org</code>
    (you may also want to join <code>xsp-dev@xml.apache.org</code>), install and try out Cocoon
    and read some of the <link href="mail-lists.html">mail archives</link>.
    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!)</li>
   <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 <code>.zip</code> and
    <code>.tar.gz</code> packages, but anyone is welcome to build their own specific packages and
    announce them on <code>cocoon-users</code>)</li>
   <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>
  </ul>
 
  <p>
   Thank you very much. 
  </p>
 </section>

 <section id="contrib">
 <title>Contributions of Code and Documentation</title>
   <p>
     If you have a contribution that you would like to see incorporated into
     the Cocoon distribution, then please take note of the 
     <link href="#license">licensing requirements</link> listed below,
     and then read the section 
     <link href="#procedure">Procedure for Raising Development Issues</link>.
   </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, Bugzilla.
   </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>
  
  <section id="testing">
  <title>Testing Requirements for Cocoon Contrib and Distribution</title>
   <p>All new code should be tested under at least the following servlet engines:</p>
   <ul>
    <li>Apache Tomcat 3.2.2</li>
   </ul>
   <p>It should also be tested on the following platforms:</p>
   <ul>
    <li>A Windows operating system</li>
    <li>A UNIX-type operating system</li>
    <li>At least JDK version 1.3.x</li>
   </ul>
   <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 >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!</p>
  </section>

 <section id="documentation">
 <title>Documentation Requirements for Cocoon Distribution</title>
  <p>All new features (processor, logicsheets, config options etc.) should be documented
   appropriately (in XML or in <code>cocoon.xconf</code> in the case of config options).</p>

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

 <section id="license">
 <title>Licensing Requirements for the Cocoon Distribution</title>
  <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 projects:</p>
  <ul>
   <li>Source code files (which include every file, code and documentation)
   must be under the
   <link href="http://www.apache.org/licenses/">Apache license</link>.
    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 allowed.</li>
  </ul>
  <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
   contributors!</p>
  <!-- WE DON'T HAVE A CONTRIB DIRECTORY. DO WE NEED THIS NOW? UV
  <p><strong>Note:</strong> Since the <code>contrib/</code> 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.</p>
  -->
 </section>
 </section>

 <section id="svnhowto">
 <title>Subversion Usage Precis</title>
  <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
   <link href="http://subversion.tigris.org/">subversion.tigris.org</link>. Other resources include 
   <link href="http://svnbook.red-bean.com/">"Version Control with Subversion"</link> and
   <link href="http://softech.informatik.uni-kl.de/softech/content/einfothek/e2348/e2328/index_ger.html">a fast introduction</link>.
  </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>

 <section id="local-repository">
 <title>How to Establish your Local Repository</title>

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

  <ol>
   <li><code>cd /usr/local/svn/cocoon</code></li>
   <li><code>svn co http://svn.apache.org/repos/asf/cocoon/branches/BRANCH_2_1_X/</code></li>
   <li><code>cd BRANCH_2_1_X</code></li>
  </ol>

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

 <section id="updating">
 <title>How to Keep it Up-to-date</title>

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

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

 <section id="diffing">
 <title>How to Generate Differences</title>

  <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 
   <code>cocoon-dev</code> 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
   <code>xdocs/contrib.xml</code>
  </p>

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

 <section id="branches">
 <title>How to get other branches</title>
  <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 ViewCVS
   <link href="http://svn.apache.org/viewcvs.cgi/cocoon/">http://svn.apache.org/viewcvs.cgi/cocoon/</link>
   Then follow the same checkout procedure described above, using this ...
  </p>

  <ul>
   <li><code>cd /usr/local/svn/cocoon</code></li>
   <li><code>svn co http://svn.apache.org/repos/asf/cocoon/branches/BRANCHNAME</code></li>
  </ul>

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

  <ul>
   <li><code>cd /usr/local/svn/cocoon</code></li>
   <li><code>svn co http://svn.apache.org/repos/asf/cocoon/trunk cocoon-trunk</code></li>
  </ul>
 </section>
 </section>

 <section id="committer">
 <title>Committer repository access</title>
  <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 
   minotaur.apache.org and run <code>svnpasswd username</code>.  This will ask 
   you for a subversion password. This is the user and password you can use when 
   checking in code.
   See also
   <link href="http://www.apache.org/dev/version-control.html">ASF developer notes</link>
   about version control.
   </p>
 </section>

 <section id="procedure">
 <title>Procedure for Raising Development Issues</title>
  <p>Documentation contributions can usually be added directly to the
    issue tracker. First read the 
    <link href="#contrib">contribution notes</link> above, then follow the
    <link href="http://cocoon.apache.org/2.1/howto/index.html#Contribution">howto documents</link>
    about patching and about using Bugzilla.
  </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 
   <code>cocoon-dev</code> <link href="mail-lists.html">mailing list</link>
   and when to use
   <link href="http://issues.apache.org/bugzilla/">Bugzilla</link>
   (the Apache Bug Database).
  </p>

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

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

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

  <p>
   When you are sure about your proposed patch, then please submit it
   <link href="http://cocoon.apache.org/2.1/howto/index.html#Contribution">via Bugzilla</link>,
   rather than as email to <code>cocoon-dev</code>.
   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.
  </p>

  <p>
   When posting discussion topics to the <code>cocoon-dev</code> 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.
  </p>
 </section>

 <section id="tips">
 <title>Contribution Notes and Tips</title>
  <p>
   This is a collection of tips for contributing to the project in a manner
   that is productive for all parties.
  </p>

  <ul>
   <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 title.
   </li>
   <li>
    See <link href="mail-lists.html">Tips</link> for Cocoon mailing lists and 
    <link href="http://learn.to/edit_messages/">Message Editing and
    Quoting Guide (with Examples)</link>.
   </li>
   <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 &quot;Reply to&quot; button,
    because threaded mail-readers get confused (they utilise the 
    <code>In-reply-to</code> 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. <code>[Vote]</code>, <code>[Proposal]</code>, 
    <code>[RT]</code> (Random Thought which quickly blossom into research
    topics :-), <code>[STATUS]</code> (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 
    <link href="http://www.oasis-open.org/cover/">validating parser</link>
    (one that is tried and true is
    <link href="http://openjade.sourceforge.net/">OpenSP/onsgmls</link>).
    This procedure will detect errors without having to go through the whole
    <code>build docs</code> 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>
   <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>
  </ul>
 </section>

</body>
</document>
