The attached patch enhances the explanations of contribution
methods and adds a couple more tips.
David Crossley
Index: contrib.xml
===================================================================
RCS file: /home/cvspublic/xml-cocoon2/xdocs/contrib.xml,v
retrieving revision 1.6
diff -u -r1.6 contrib.xml
--- contrib.xml 2001/08/16 10:03:15 1.6
+++ contrib.xml 2001/09/11 08:46:32
@@ -82,7 +82,7 @@
there. (The @docname@ 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 <code>cocoon-users</code>)</li>
- <li>... and there is just one other thing - don't forget to tell everyone who asks
how great @doctitle@ is! ;-)
+ <li>... and there is just one other thing - don't forget to tell everyone who
+asks, how great @docname@ is! ;-)
The more people that know about and start to use @docname@, the larger the pool of
potential contributors there will be
- so, please, help us by placing the @docname@ logo somewhere in your
@@ -243,20 +243,20 @@
<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 ...
+ will be applied to the master. Exactly the opposite will happen - updates
+ from the remote master version are merged into your local repository.
+ 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>
+ <br/><code>update -d -P -r HEAD xml-cocoon2</code></li>
+ <li><strong>... pay attention to the update messages</strong></li>
<li><code>cvs -d :pserver:[EMAIL PROTECTED]:/home/cvspublic logout</code></li>
</ol>
</s2>
@@ -266,8 +266,10 @@
<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).
+ this, along with an explanation of why it is required, to the
+ <code>cocoon-dev</code> mailing list. One of the authorised
+ maintainers of the repository will review the patch and then apply it to the
+ relevant branch.
</p>
<p>
@@ -276,6 +278,8 @@
</p>
<ol>
+ <li>Make the desired changes in your local repository, build, test it
+ thoroughly</li>
<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>
@@ -305,6 +309,13 @@
</p>
<p>
+ Most issues will be discovered, resolved, and then patched quickly
+ via the <code>cocoon-dev</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
@@ -325,8 +336,9 @@
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
+ will have holidays at different times to your country and that they are
+ in different time zones. You might also consider re-writing your initial
+ posting - perhaps it was not clear enough
and the readers' eyes glazed over.
</p>
</s1>
@@ -349,14 +361,20 @@
descriptive title.
</li>
<li>
+ Prepend your email subject line with <code>[Patch]</code>, or
+ <code>[Proposal]</code>, or something else, when that is appropriate.
+ </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).
+ (one that is tried and true is
+ <link href="http://www.jclark/sp/";>SP/nsgmls</link>).
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.
+ 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
@@ -376,9 +394,24 @@
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>
- Do not send an email reply that simply says "thanks". When the issue is
- resolved, that is the finish - end of thread. Reduce clutter.
+ 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
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, email: [EMAIL PROTECTED]
