<?xml version="1.0" encoding="UTF-8"?>
<!--
  Copyright 2002-2004 The Apache Software Foundation or its licensors,
  as applicable.

  Licensed under the Apache License, Version 2.0 (the "License");
  you may not use this file except in compliance with the License.
  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
-->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "http://forrest.apache.org/dtd/document-v12.dtd">
<document>
  <header>
    <title>Contributing to Apache Forrest</title>
  </header>
  <body>
    <section id="introduction">
      <title>Introduction</title>
      <p> The Forrest Project is an <link href="http://www.opensource.org/">Open Source</link> volunteer project released
      under a very liberal 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="site:SVN">latest and
      greatest code</link> (which you find in the Forrest module in the SVN 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 id="wanted">
     <title>Help Wanted Here</title>
      <p>We would be glad to have extra help in any of the following areas:
      </p>
      <ul>
        <li>Assisting to improve documentation.</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 as issues (see <link href="#procedure">explanation
      below</link>).</li>
        <li>Providing new use-cases and requirements. If you think that
        Forrest does not quite meet your needs then tell us about it.</li>
      <li>Specifying/analysing/designing new features - and beyond. If you
        wish to get further involved with this, please join the <code>forrest-dev</code> mailing
        list, install and try out Forrest and read some of the
        <link href="site:mail-lists">mail archives</link>. You should have a reasonable
      fluency in XML technologies, some Java and Ant skills, and a basic understanding of the Forrest
      architecture - don't just say "it should have XYZ" without reading anything
      first - because chances are, somebody has 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>forrest-dev</code> list)</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>

    <section id="issues">
    <title>Procedure for reporting bugs and issues and enhancement suggestions</title>
      <p>
        If you think that you have found a bug or you have a suggestion for
        improvement, then please discuss it on
        one of the <link href="site:mail-lists">mailing lists</link>.
        However, please check our Issue Tracker first as it may be already reported.
      </p>
      <p>
        The <link href="site:bugs">Apache Forrest Issue Tracker</link> collates
        our known issues. Obviously not every issue is listed there. Some issues
        have been discussed on the mailing list but do not yet have an issue recorded.
      </p>
      <p>
        The Roadmap is the best way to get an overview. The Unscheduled list also
        needs regular review, and committers will schedule some of those for the
        next release.
      </p>
      <p>
        When creating a new issue, please provide a concise Summary Title and
        a short Description. Add further information as Comments and include
        links to the mail archives. The normal procedure is to discuss the
        issue on the mailing list and then add relevant notes to the issue tracker,
        otherwise it becomes cluttered.
      </p>
    </section>

    <section id="cvshowto">
    <title>SVN Usage</title>
      <p>An overview of how to use Subversion (SVN) 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.
        The <link href="site:v0.70//build">Building Forrest</link> document explains.
      </p>
    </section>

    <section id="ssh">
    <title>SVN Committer with Secure Shell access</title>
      <p>After a developer has consistently provided contributions (code,
        documentation and discussion) and demonstrated committment, then the rest of the dev community may vote to
        grant this developer commit access to the Subversion repository.
        See the <link href="http://www.apache.org/dev/">ASF developers resources</link>
        especially the 
        <link href="http://www.apache.org/dev/version-control.html">Source code repositories</link>.
      </p>
      <p>You will need secure access to the repository to be able to commit
        patches. Commits to the SVN repository must use the https: protocol.
        If you already have the codebase
        checked out via the http: protocol, then the following command will
        convert it.</p>
      <source>svn sw https://svn.apache.org/repos/asf/forrest/trunk</source>
      <p>Line ending issues can be a problem when committing, since developers use
        both Linux and Windows.  SVN can understand that files are text (as opposed to binary like images), but
        this must be specified for every new file added. Your SVN client
        can be 
        <link href="http://www.apache.org/dev/version-control.html#https-svn">configured</link>
        to automatically do this for certain file extensions.
        To do it manually, make sure all line endings
        are in your current OS's native format (the dos2unix and unix2dos utilities
        may be useful) and then do a <code>svn propset svn:eol-style native myfilename.txt</code>
        and <code>svn commit -m "fix line endings" myfilename.txt</code>
      </p>
    </section>

    <section id="procedure">
    <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 developer
        <link href="site:mail-lists">mailing list</link> and the
        <link href="site:forrest-issues">issue tracker</link>. </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 developer mailing list. Larger issues, and ones that are
        not yet fully understood or are hard to solve, are destined for the issue tracker. </p>
      <p> Experienced developers use the issue tracker 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 the issue tracker 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 developers
        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>

    <section id="patch">
     <title>How to prepare and contribute patches</title>
     <p>If you use the current development version of Forrest, then do
       '<code>svn update; svn status</code>' to see what files that you
       have changed.
       Do '<code>svn diff > mypatch.txt</code>' to make a patch which
       includes every change. To make a patch for a specific file, do
       <code>svn diff src/documentation/content/xdocs/faq.xml > faq.xml.diff</code>'.
       For more information about working with SVN, see
       <link href="http://svnbook.red-bean.com/">Version Control with
       Subversion</link> - the opensource SVN book.
      </p>
      <p>If you use a downloaded released version of Forrest, then do
        '<code>diff -u faq.xml.orig faq.xml > faq.xml.diff</code>'
      </p>
      <note>Please send all contributions via our
        <link href="site:bugs">issue tracker</link>.
      </note>
      <p>
        It is always a good idea to check the Forrest
        <link href="site:bugs">issue tracker</link>
        before diving in.
      </p>
    </section>
    
    <section id="revert">
      <title>How to revert changes in SVN</title>
      <p>Check out <link href="http://svnbook.red-bean.com/en/1.0/ch04s04.html#svn-ch-4-sect-4.2">http://svnbook.red-bean.com/en/1.0/ch04s04.html#svn-ch-4-sect-4.2</link> 
      for instructions on how to revert (roll back) changes to svn.</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>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>[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 validating XML editor. Here is some assistance
          with editor
          <link href="site:v0.70//catalog">configuration</link>.
        </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 trunk of
        SVN. </li>
      <li> When sending a patch, you usually do not need to worry about which
        SVN branch it should be applied to. The maintainers of the repository will
        decide. </li>
      <li>Keep all project-related discussion on the mailing list. It is much
        better to utilise the wider audience, rather than to break off into
        private discussion groups. You never know who else will have the
        answer to your issues, and anyway other people are interested in
        the outcome.
      </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>
