<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "http://apache.org/forrest/dtd/document-v12.dtd">
<document>
  <header>
    <title>Contributing to Forrest</title>
    <authors> <person name="Stefano Mazzocchi" email="stefano@apache.org"/>
      <person name="Nicola Ken Barozzi" email="nicolaken@apache.org"/>
    </authors>
  </header>
  <body>
    <section>
      <title>Introduction</title>
      <p> The Forrest Project is an <link href="http://www.opensource.org/">Open Source</link> 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...). </p>
      <p> To begin with, we suggest you to subscribe to the
        <link href="site:mail-lists">Forrest 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 contributions. </p>
      <p>You can get your local working copy of the
        <link href="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/Forrest">latest and
      greatest code</link> (which you find in the Forrest module in the CVS code
      repository. 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, and post to the dev mailing list. (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>
     <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>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 Forrest (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 To Do, and some are
          recorded in Bugzilla (see <link href="#procedure">explanation
      below</link>).</li>
      <li>Specifying/analysing/designing new features - and beyond. (If you
        wish to get involved with this, please join <code>general Forrest mailing
        list</code>, install and try out Forrest and read some of the
        <link href="site:mail-lists">mail archives</link>. You should have a strong
      "fluency" in XML technologies, Java and a basic understanding of the Forrest
      architecture - don't just say "it should have XYZ" without reading anything
      first - because chances are, somebodies already thought of that feature!)</li>
      <li>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 <code>.zip</code> and <code>.tar.gz</code> packages, but anyone is
        welcome to build their own specific packages and announce them on the
        <code>general Forrest list</code>)</li>
      <li>... and there is just one other thing - don't forget to tell everyone
        who asks, how great Forrest is! ;-) The more people that know about and start
        to use Forrest, the larger the pool of potential contributors there will be.
        </li>
      </ul>
    </section> <anchor id="cvshowto"/>
    <section>
    <title>CVS Usage Precis</title>
      <p>An overview of how to use CVS to participate in Forrest 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 CVS usage information is at
        <link href="http://www.cvshome.org/">www.cvshome.org</link> and your local
      <code>info cvs</code> pages or <code>man cvs</code> pages or user
      documentation.) </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> <anchor id="ssh"/>
    <section>
    <title>CVS Committer with Secure Shell access</title>
      <p>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. </p>
      <p>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. </p>
      <ul>
        <li><link href="http://cvsbook.red-bean.com/">The CVS Book</link></li>
      <li><link href="http://www.cvshome.org/">www.cvshome.org</link></li>
      <li><link href="https://sourceforge.net/cvs/?group_id=32701"></link> -
      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.</li>
      </ul>
    </section> <anchor id="procedure"/>
    <section>
    <title>Procedure for Raising Development Issues</title>
      <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>developer</code>
        <link href="site:mail-lists">mailing list</link> the 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>developer</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 Forrest or their own installation/configuration mistake - please do
        not do this. </p>
      <p> As a rule-of-thumb, discuss an issue on the <code>developers</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 or
        patch via Bug Tracking. </p>
      <p> 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 rewriting your initial posting - perhaps it was not clear
        enough and the readers eyes glazed over. </p>
    </section> <anchor id="tips"/>
    <section>
     <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>Start new threads with new Subject for new topics, rather than
          reusing the previous Subject line. </li>
        <li>Keep each topic focused. If some new topic arises then start a new
          discussion. This leaves the original topic to continue uncluttered. </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
          unanswered. </li>
        <li> Prepend your email subject line with a marker when that is
          appropriate, e.g. <code>[Patch]</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> 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 Forrest 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.) </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> You would usually do any development work against the HEAD branch of
        CVS. </li>
      <li> 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. </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>
