Google Git
Sign in
apache / forrest / refs/tags/forrest_09_release_site / . / contrib.html
blob: 198bf4df6e74d53bf6170ed2c3c3d148be2417a9 [file] [log] [blame]
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta content="Apache Forrest" name="Generator">
<meta name="Forrest-version" content="0.9-dev">
<meta name="Forrest-skin-name" content="pelt">
<title>Contributing to Apache Forrest</title>
<link type="text/css" href="skin/basic.css" rel="stylesheet">
<link media="screen" type="text/css" href="skin/screen.css" rel="stylesheet">
<link media="print" type="text/css" href="skin/print.css" rel="stylesheet">
<link type="text/css" href="skin/profile.css" rel="stylesheet">
<script src="skin/getBlank.js" language="javascript" type="text/javascript"></script><script src="skin/getMenu.js" language="javascript" type="text/javascript"></script><script src="skin/fontsize.js" language="javascript" type="text/javascript"></script>
<link rel="shortcut icon" href="favicon.ico">
</head>
<body onload="init()">
<script type="text/javascript">ndeSetTextSize();</script>
<div id="top">
<!--+
|breadtrail
+-->
<div class="breadtrail">
<a href="http://www.apache.org/">Apache Software Foundation</a> &gt; <a href="http://forrest.apache.org/">Apache Forrest</a><script src="skin/breadcrumbs.js" language="JavaScript" type="text/javascript"></script>
</div>
<!--+
|header
+-->
<div class="header">
<!--+
|start group logo
+-->
<div class="grouplogo">
<a href="http://www.apache.org/"><img class="logoImage" alt="Apache" src="images/apache-forrest.png" title="The Apache Software Foundation"></a>
</div>
<!--+
|end group logo
+-->
<!--+
|start Project Logo
+-->
<div class="projectlogo">
<a href="http://forrest.apache.org/"><img class="logoImage" alt="Forrest" src="images/project-logo.gif" title="Apache Forrest"></a>
</div>
<!--+
|end Project Logo
+-->
<!--+
|start Search
+-->
<div class="searchbox">
<form action="http://www.google.com/search" method="get" class="roundtopsmall">
<input value="forrest.apache.org" name="sitesearch" type="hidden"><input onFocus="getBlank (this, 'Search the site with google');" size="25" name="q" id="query" type="text" value="Search the site with google">&nbsp;
<input name="Search" value="Search" type="submit">
</form>
</div>
<!--+
|end search
+-->
<!--+
|start Tabs
+-->
<ul id="tabs">
<li>
<a class="unselected" href="index.html">Welcome</a>
</li>
<li class="current">
<a class="selected" href="contrib.html">Developers</a>
</li>
<li>
<a class="unselected" href="versions/index.html">Versioned Docs</a>
</li>
<li>
<a class="unselected" href="pluginDocs/index.html">Plugins</a>
</li>
<li>
<a class="unselected" href="tools/index.html">Tools</a>
</li>
</ul>
<!--+
|end Tabs
+-->
</div>
</div>
<div id="main">
<div id="publishedStrip">
<!--+
|start Subtabs
+-->
<div id="level2tabs"></div>
<!--+
|end Endtabs
+-->
<script type="text/javascript"><!--
document.write("Last Published: " + document.lastModified);
// --></script>
</div>
<!--+
|breadtrail
+-->
<div class="breadtrail">
&nbsp;
</div>
<!--+
|start Menu, mainarea
+-->
<!--+
|start Menu
+-->
<div id="menu">
<div onclick="SwitchMenu('menu_selected_1.1', 'skin/')" id="menu_selected_1.1Title" class="menutitle" style="background-image: url('skin/images/chapter_open.gif');">Getting involved</div>
<div id="menu_selected_1.1" class="selectedmenuitemgroup" style="display: block;">
<div class="menupage">
<div class="menupagetitle">Contributing</div>
</div>
<div class="menuitem">
<a href="mail-lists.html" title="Discussion mail lists are the heart of the project: dev, user, svn">Mail lists and discussion</a>
</div>
<div class="menuitem">
<a href="issues.html" title="Issue tracker manages known issues and desired enhancements">Reporting bugs and issues</a>
</div>
<div class="menuitem">
<a href="forrest-friday.html" title="ForrestFriday monthly get-together">ForrestFriday IRC</a>
</div>
<div class="menuitem">
<a href="events.html" title="List of upcoming related conferences and meetings">Events</a>
</div>
<div onclick="SwitchMenu('menu_1.1.6', 'skin/')" id="menu_1.1.6Title" class="menutitle">Project</div>
<div id="menu_1.1.6" class="menuitemgroup">
<div class="menuitem">
<a href="guidelines.html" title="Open development guidelines to encourage participation">Project guidelines</a>
</div>
<div class="menuitem">
<a href="committed.html" title="Notes about contribution">Being committed</a>
</div>
<div class="menuitem">
<a href="tasks.html" title="Tasks to keep the project flowing">Project tasks</a>
</div>
</div>
</div>
<div onclick="SwitchMenu('menu_1.2', 'skin/')" id="menu_1.2Title" class="menutitle">Resources and Infrastructure</div>
<div id="menu_1.2" class="menuitemgroup">
<div class="menuitem">
<a href="asf-infrastructure.html" title="Explain the ASF infrastructure">Introduction</a>
</div>
<div class="menuitem">
<a href="mail-lists.html" title="Discussion mail lists are the heart of the project: dev, user, svn">Mail lists</a>
</div>
<div class="menuitem">
<a href="issues.html" title="Issue tracker manages known issues and desired enhancements">Issue management</a>
</div>
<div class="menuitem">
<a href="svn.html" title="Access to the Subversion (SVN) version control system">Version control</a>
</div>
<div class="menuitem">
<a href="http://forrest.zones.apache.org/" title="Demonstrations and testbed at forrest.zones.apache.org">Demonstrations</a>
</div>
<div class="menuitem">
<a href="gump.html">Gump integration</a>
</div>
<div onclick="SwitchMenu('menu_1.2.7', 'skin/')" id="menu_1.2.7Title" class="menutitle">Planning notes</div>
<div id="menu_1.2.7" class="menuitemgroup">
<div class="menuitem">
<a href="plan/index.html">Overview</a>
</div>
<div class="menuitem">
<a href="plan/internal-xhtml.html">Internal XHTML</a>
</div>
</div>
<div class="menuitem">
<a href="todo.html">Todo</a>
</div>
</div>
<div onclick="SwitchMenu('menu_1.3', 'skin/')" id="menu_1.3Title" class="menutitle">Best Practices and Procedures</div>
<div id="menu_1.3" class="menuitemgroup">
<div class="menuitem">
<a href="howto-dev.html" title="Describes tips and procedures for efficiently developing with Forrest.">Development tips</a>
</div>
<div class="menuitem">
<a href="howto-forrestbot-svn.html" title="Publish documentation with Forrestbot svn workstage">Forrestbot svn</a>
</div>
<div class="menuitem">
<a href="howto-forrestbot-scp.html" title="Publish documentation with Forrestbot scp workstage">Forrestbot scp</a>
</div>
<div class="menuitem">
<a href="subversion_bestpractices.html" title="Best practice notes for Subversion">Subversion</a>
</div>
<div class="menuitem">
<a href="documentation_bestpractices.html" title="Best practice notes for documentation">Documentation</a>
</div>
<div class="menuitem">
<a href="howto-howto.html" title="Instructions for writing a new howto-document">Write a How-to</a>
</div>
<div onclick="SwitchMenu('menu_1.3.7', 'skin/')" id="menu_1.3.7Title" class="menutitle">Committer notes</div>
<div id="menu_1.3.7" class="menuitemgroup">
<div class="menuitem">
<a href="zone.html" title="Notes for committers to manage forrest.zones.apache.org">Zone management</a>
</div>
<div class="menuitem">
<a href="procedures/release/How_to_release.html" title="Instructions on preparing and creating a new Forrest release.">How to release</a>
</div>
<div class="menuitem">
<a href="procedures/How_to_publish_docs.html" title="Instructions on publishing the Forrest Website">Publishing Forrest documentation</a>
</div>
</div>
</div>
<div onclick="SwitchMenu('menu_1.4', 'skin/')" id="menu_1.4Title" class="menutitle">Proposals</div>
<div id="menu_1.4" class="menuitemgroup">
<div class="menuitem">
<a href="proposal-asf-forrestbot.html">ASF Forrestbot</a>
</div>
</div>
<div id="credit"></div>
<div id="roundbottom">
<img style="display: none" class="corner" height="15" width="15" alt="" src="skin/images/rc-b-l-15-1body-2menu-3menu.png"></div>
<!--+
|alternative credits
+-->
<div id="credit2">
<a href="http://www.apache.org/events/current-event.html"><img border="0" title="ApacheCon" alt="ApacheCon - logo" src="http://www.apache.org/events/current-event-125x125.png" style="width: 125px;height: 125px;"></a>
</div>
</div>
<!--+
|end Menu
+-->
<!--+
|start content
+-->
<div id="content">
<div class="trail">Font size:
&nbsp;<input value="Reset" class="resetfont" title="Reset text" onclick="ndeSetTextSize('reset'); return false;" type="button">
&nbsp;<input value="-a" class="smallerfont" title="Shrink text" onclick="ndeSetTextSize('decr'); return false;" type="button">
&nbsp;<input value="+a" class="biggerfont" title="Enlarge text" onclick="ndeSetTextSize('incr'); return false;" type="button">
</div>
<h1>Contributing to Apache Forrest</h1>
<div id="front-matter">
<div id="minitoc-area">
<ul class="minitoc">
<li>
<a href="#introduction">Introduction</a>
</li>
<li>
<a href="#wanted">Help Wanted Here</a>
</li>
<li>
<a href="#issues">Procedure for reporting bugs and issues and enhancement suggestions</a>
</li>
<li>
<a href="#cvshowto">SVN Usage</a>
</li>
<li>
<a href="#ssh">SVN Committer with Secure Shell access</a>
</li>
<li>
<a href="#procedure">Procedure for Raising Development Issues</a>
</li>
<li>
<a href="#patch">How to prepare and contribute patches</a>
</li>
<li>
<a href="#revert">How to revert changes in SVN</a>
</li>
<li>
<a href="#tips">Contribution Notes and Tips</a>
</li>
</ul>
</div>
</div>
<a name="introduction"></a>
<h2 class="underlined_10">Introduction</h2>
<div class="section">
<p>
The Forrest Project is an <a href="http://www.opensource.org/" rel="nofollow">Open
Source</a> 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 (staff time, conference presentations, publicity,
software) and even general hardware/money
<a href="http://www.apache.org/foundation/thanks.html">donations</a>
via the ASF.
</p>
<p>
To begin with, we suggest you to subscribe to the
<a href="mail-lists.html">Forrest 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 contributions.
</p>
<p>
You can get your local working copy of the
<a href="docs_0_90/howto/../build.html">latest and greatest code</a> (which you find
in the Forrest module in the Subversion code repository). Review the
todo list and the issue tracker, choose a task. Perhaps you have noticed
something that needs patching, or have a new feature to contribute. Make
the changes, do the testing, generate a patch, and discuss on 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>
</div>
<a name="wanted"></a>
<h2 class="underlined_10">Help Wanted Here</h2>
<div class="section">
<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>New samples for the 'forrest seed-sample' to concisely describe
and demonstrate features. Such samples can also enable automated testing.</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 <a href="#procedure">explanation
below</a>).</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 <span class="codefrag">forrest-dev</span> mailing
list, install and try out Forrest and read some of the
<a href="mail-lists.html">mail archives</a>. 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 <span class="codefrag">.zip</span> and <span class="codefrag">.tar.gz</span> packages, but anyone is
welcome to build their own specific packages and announce them on the
<span class="codefrag">forrest-dev</span> 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 will be.
</li>
</ul>
</div>
<a name="issues"></a>
<h2 class="underlined_10">Procedure for reporting bugs and issues and enhancement suggestions</h2>
<div class="section">
<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
<a href="mail-lists.html">mailing lists</a>. However, please check
our Issue Tracker first as it may be already reported.
</p>
<p>
The <a href="issues.html">Apache Forrest Issue Tracker</a> 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>
</div>
<a name="cvshowto"></a>
<h2 class="underlined_10">SVN Usage</h2>
<div class="section">
<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
<a href="docs_0_90/howto/../build.html">Building Forrest</a> document
explains.
</p>
</div>
<a name="ssh"></a>
<h2 class="underlined_10">SVN Committer with Secure Shell access</h2>
<div class="section">
<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
<a href="http://www.apache.org/dev/">ASF developers resources</a>
especially the
<a href="http://www.apache.org/dev/version-control.html">Source code
repositories</a>.
</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>
<pre class="code">svn sw https://svn.apache.org/repos/asf/forrest/trunk</pre>
<a name="svn-config"></a>
<p id="svn-config">
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
<a href="http://www.apache.org/dev/version-control.html#https-svn">configured</a>
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 <span class="codefrag">svn
propset svn:eol-style native myfilename.txt</span> and <span class="codefrag">svn commit
-m "fix line endings" myfilename.txt</span>
</p>
</div>
<a name="procedure"></a>
<h2 class="underlined_10">Procedure for Raising Development Issues</h2>
<div class="section">
<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
<a href="mail-lists.html">mailing list</a> and the
<a href="issues.html">issue tracker</a>.
</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>
</div>
<a name="patch"></a>
<h2 class="underlined_10">How to prepare and contribute patches</h2>
<div class="section">
<p>
If you use the current development version of Forrest via Subversion,
then do '<span class="codefrag">svn update; svn status</span>' to see what files that you
have changed. Do '<span class="codefrag">svn diff &gt; mypatch.txt</span>' to make a patch
which includes every change. To make a patch for a specific file, do
<span class="codefrag">svn diff src/documentation/content/xdocs/faq.xml &gt;
faq.xml.diff</span>'. It is better to prepare the patch from the
$FORREST_HOME directory so that it contains a definite path to the
document. However, be careful that the patch does not contain other
work-in-progress.
</p>
<p>
For more information about working with SVN, see
<a href="http://svnbook.red-bean.com/" rel="nofollow">Version Control with
Subversion</a> - the opensource SVN book.
</p>
<p>
If you use a downloaded released version of Forrest (or don't use SVN),
then use the 'diff' command of your operating system: '<span class="codefrag">diff -u
faq.xml.orig faq.xml &gt; mypatch.txt</span>' (better to do that from
$FORREST_HOME directory). If you want to use the most recent version of
the documentation then grab its source file directly from the
<a href="http://svn.apache.org/repos/asf/forrest/trunk/site-author/content/xdocs/">SVN
server</a> (and tell us which Revision number you used).
</p>
<div class="note">
<div class="label">Note</div>
<div class="content">
Please send all contributions via our <a href="issues.html">issue
tracker</a>. and specify the Forrest version or svn version of the
source.
</div>
</div>
<p>
It is always a good idea to check the Forrest
<a href="issues.html">issue tracker</a> before diving in.
</p>
</div>
<a name="revert"></a>
<h2 class="underlined_10">How to revert changes in SVN</h2>
<div class="section">
<p>
Check out
<a href="http://svnbook.red-bean.com/en/1.0/ch04s04.html#svn-ch-4-sect-4.2" rel="nofollow">http://svnbook.red-bean.com/en/1.0/ch04s04.html#svn-ch-4-sect-4.2</a>
for instructions on how to revert (roll back) changes to svn.
</p>
</div>
<a name="tips"></a>
<h2 class="underlined_10">Contribution Notes and Tips</h2>
<div class="section">
<p>
This is a collection of tips for contributing to the project in a manner
that is productive for all parties.
</p>
<ul>
<li>See general ASF
<a href="http://www.apache.org/dev/contrib-email-tips.html">Tips for email contributors</a>
</li>
<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 "Reply to" button, because
threaded mail-readers get confused (they utilise the <span class="codefrag">In-reply-to</span>
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. <span class="codefrag">[Proposal]</span>,
<span class="codefrag">[RT]</span> (Random Thought which quickly blossom into research topics
:-), <span class="codefrag">[STATUS]</span> (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
<a href="docs_0_90/catalog.html">configuration</a>.
</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>
</div>
</div>
<!--+
|end content
+-->
<div class="clearboth">&nbsp;</div>
</div>
<div id="footer">
<!--+
|start bottomstrip
+-->
<div class="lastmodified">
<script type="text/javascript"><!--
document.write("Last Published: " + document.lastModified);
// --></script>
</div>
<div class="copyright">
Copyright &copy;
2002-2011 <a href="http://www.apache.org/licenses/">The Apache Software Foundation. Licensed under Apache License 2.0</a>
<br>
Apache, Apache Forrest, the Apache feather logo, and the Apache Forrest
logos are trademarks of The Apache Software Foundation.
</div>
<!--+
|end bottomstrip
+-->
</div>
</body>
</html>