forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From cross...@apache.org
Subject svn commit: rev 20590 - xml/forrest/trunk/src/documentation/content/xdocs
Date Sat, 29 May 2004 12:24:25 GMT
Author: crossley
Date: Sat May 29 05:24:24 2004
New Revision: 20590

Modified:
   xml/forrest/trunk/src/documentation/content/xdocs/contrib.xml
Log:
Refine the text.


Modified: xml/forrest/trunk/src/documentation/content/xdocs/contrib.xml
==============================================================================
--- xml/forrest/trunk/src/documentation/content/xdocs/contrib.xml	(original)
+++ xml/forrest/trunk/src/documentation/content/xdocs/contrib.xml	Sat May 29 05:24:24 2004
@@ -23,7 +23,7 @@
     <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
+      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
@@ -43,60 +43,64 @@
         help but you're not familiar with the innermost technical details, don't worry:
         we have work for you! </p>
     </section>
-    <section>
+    <section id="wanted">
      <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>
+      <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>Specifying/analysing/designing new features - and beyond. (If you
-        wish to get involved with this, please join the <code>forrest-dev</code>
mailing
+        <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
strong
-      "fluency" in XML technologies, Java and a basic understanding of the Forrest
+        <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, somebodies already thought of that feature!)</li>
+      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
+        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>
+    </section>
+
+    <section id="cvshowto">
     <title>SVN Usage</title>
-      <p>An overview of how to use SVN to participate in Forrest development.
+      <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. </p>
-      <p> (Further general SVN usage information is at
-        <link href="http://subversion.tigris.org/">subversion.tigris.org</link>
and your local
-      <code>info svn</code> pages or <code>man svn</code> pages or
user
-      documentation.) </p>
-    </section> <anchor id="ssh"/>
-    <section>
+        local repository and compare your revisions with the real repository.
+        The <link href="site: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), then the rest of the dev community may vote to
+        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. </p>
       <p>You will need secure access to the repository to be able to commit
-        patches. The <link href="site:build">building page</link> should have
all the instructions you need to get your machine configured to use the repository. </p>
-      <p>Commits to the SVN repository must go through https:  If you have the codebase
-        checked out via http:, the following will convert it.</p>
+        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/xml/forrest/trunk</source>
-    </section> <anchor id="procedure"/>
-    <section>
+    </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
@@ -127,8 +131,9 @@
         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>
+    </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>
@@ -152,14 +157,10 @@
           <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>
-
+          that matter, use a validating XML editor. Here is some assistance
+          with editor 
+          <link href="catalog.html">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>
@@ -179,10 +180,12 @@
       <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> 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>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>
 

Mime
View raw message