I have added three new sections to contrib.xml to
help contributers to be more productive:
* CVS Usage Precis
- an overview of how to get started with CVS
* Procedure for Raising Development Issues
- when to use Bugzilla and when to post to cocoon-dev
* Contribution Notes and Tips
- a list of dot-points
While there i noticed that the element <connect> was
being used to link to other documents. However, that
element is not rendered by the stylesheet. So I changed
them all to <link> and now everything is OK.
The patch is attached.
cheers, David Crossley
Index: contrib.xml
===================================================================
RCS file: /home/cvspublic/xml-cocoon2/xdocs/contrib.xml,v
retrieving revision 1.5
diff -u -r1.5 contrib.xml
--- contrib.xml 2001/07/28 22:00:11 1.5
+++ contrib.xml 2001/08/15 14:51:06
@@ -29,14 +29,18 @@
</p>
<p>
To begin with, we suggest you to subscribe to the
- <connect href="mail-lists.xml">@docname@ mailing lists</connect>
+ <link href="mail-lists.html">@docname@ mailing lists</link>
(follow the link for information on how to subscribe and to access the mail
- list archives), to checkout the <link
href="http://xml.apache.org/websrc/index.cgi/xml-cocoon2/";>
- latest and greatest code</link> (which you find in the xml-cocoon2 module in
+ list archives), to checkout the
+ <link href="http://cvs.apache.org/viewcvs.cgi/xml-cocoon2/";>latest and
+ greatest code</link> (which you find in the xml-cocoon2 module in
the cvs.apache.org CVS code repository, or from the
<link href="http://xml.apache.org/from-cvs/xml-cocoon2/";>CVS snapshots</link>),
- control the <connect href="todo.xml">todo</connect>
- list and jump in. Document writers are usually the most wanted people so if
+ control the <link href="todo.html">todo</link>
+ list and jump in.
+ </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>
@@ -64,13 +68,13 @@
having too many questioners and not enough experts to respond to all the
questions.</li>
<li>Testing @docname@ (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
(at the time of
- writing, some known bugs are informally listed on <connect href="todo.xml">To
Do</connect>, but
- eventually a bug database should be made available on the Apache site).</li>
+ <li>Debugging - producing reproduceable test cases and/or finding causes of bugs.
+Some known bugs are informally listed on
+ <link href="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 @docname@ - and beyond. (If
you wish to get involved
with this, please join <code>[EMAIL PROTECTED]</code>
(you may also want to join <code>[EMAIL PROTECTED]</code>), install and try
out @doctitle@
- and read some of the <link href="http://mail-archives.apache.org/";>mail
archives</link>.
+ 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 @doctitle@ architecture - don't just say "it should have XYZ" without reading
anything first -
because chances are, someone's already thought of that feature!)</li>
@@ -102,14 +106,14 @@
<p>If your contribution requires changing more than a few lines of @docname@ (code
or
documentation), then it counts as a <strong>patch</strong>. If you have a patch and
would like to see it incorporated into the @docname@ distribution, take note of
the Licensing
- Requirements listed below, and then read the <connect href="patches.xml">Patch
management
- </connect> page for more information.
+ Requirements listed below, and then read the section
+ <link href="#procedure">Procedure for Raising Development Issues</link>
</p>
<p>Otherwise (that is, if it does not require patching or you are not particularly
interested in
having it included in the main distribution), your code and/or
documentation can be listed on the
- <connect href="3rdparty.xml">Third-Party Contributions</connect> page.
+ <link href="3rdparty.html">Third-Party Contributions</link> page.
The rationale for this split is that core patches may fix important issues, and
may
require timely attention if they are not to go
out-of-date and become useless, but other contributions can simply be downloaded
and
@@ -185,5 +189,203 @@
- but it must still be released under the Apache license.</p>
</s2>
</s1>
+
+ <anchor id="cvshowto"/>
+ <s1 title="CVS Usage Precis">
+ <p>An overview of how to use CVS to participate in @docname@ 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>
+
+ <s2 title="How to Establish your Local Repository">
+
+ <p>
+ This will checkout the current copy of the master cvs repository and
+ download it to your local disk. It will create a sub-directory called
+ <code>xml-cocoon2</code>
+ </p>
+
+ <ol>
+ <li><code>cd /usr/local/cvs</code></li>
+ <li><code>cvs -d :pserver:[EMAIL PROTECTED]:/home/cvspublic login</code></li>
+ <li>... use this password: <code>anoncvs</code></li>
+ <li><code>cvs -d :pserver:[EMAIL PROTECTED]:/home/cvspublic -z3 \</code>
+ <br/><code>checkout -r HEAD xml-cocoon2</code></li>
+ <li><code>cvs -d :pserver:[EMAIL PROTECTED]:/home/cvspublic logout</code></li>
+ <li><code>cd xml-cocoon2</code></li>
+ </ol>
+
+ <p>
+ You now have the HEAD branch of the current development cvs repository
+ for @doctitle@ on your local system. Go ahead and build and deploy as
+ usual. Make some changes, re-build, and see the effect.
+ </p>
+ </s2>
+
+ <s2 title="How to Keep it Up-to-date">
+
+ <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 - the
+ remote master version is synchronised with yours. 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/cvs</code></li>
+ <li><code>cvs -d :pserver:[EMAIL PROTECTED]:/home/cvspublic login</code></li>
+ <li><code>cvs -d :pserver:[EMAIL PROTECTED]:/home/cvspublic -z3 \</code>
+ <br/><code>update -r HEAD xml-cocoon2</code></li>
+ <li>... pay attention to the update messages</li>
+ <li><code>cvs -d :pserver:[EMAIL PROTECTED]:/home/cvspublic logout</code></li>
+ </ol>
+ </s2>
+
+ <s2 title="How to Generate Differences">
+
+ <p>
+ To contribute your modifications, you need to produce a plain-text file
+ containing the differences between the master copy and yours. You will send
+ this, along with an explanation of why it is required, to the authorised
+ maintainers of the repository (via the procedures described below).
+ </p>
+
+ <p>
+ We will assume that you are adding some tips to this document
+ <code>xdocs/contrib.xml</code>
+ </p>
+
+ <ol>
+ <li><code>cd /usr/local/cvs/xml-cocoon2/xdocs</code></li>
+ <li><code>cvs -d :pserver:[EMAIL PROTECTED]:/home/cvspublic login</code></li>
+ <li><code>cvs diff -u contrib.xml > $WORK/cocoon/contrib.xml.diff</code></li>
+ <li><code>cvs -d :pserver:[EMAIL PROTECTED]:/home/cvspublic logout</code></li>
+ </ol>
+ </s2>
+ </s1>
+
+ <anchor id="procedure"/>
+ <s1 title="Procedure for Raising Development Issues">
+ <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://nagoya.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>
+ 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 @docname@ 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 or patch via Bugzilla.
+ </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
+ may have holidays at different times to your country. You might also
+ consider re-writing your initial posting - perhaps it was not clear enough
+ and the readers' eyes glazed over.
+ </p>
+ </s1>
+
+ <anchor id="tips"/>
+ <s1 title="Contribution Notes and Tips">
+ <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>
+ 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>
+ (we use SP/nsgmls).
+ This procedure will detect errors without having to go through the whole
+ <code>build docs</code> process to find them. Do not expect @docname@
+ or the build system to detect the validation errors for you - they can
+ do it, but that is not their purpose.
+ </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 send an email reply that simply says "thanks". When the issue is
+ resolved, that is the finish - end of thread. Reduce clutter.
+ </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>
+ </s1>
+
</body>
</document>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, email: [EMAIL PROTECTED]
