cocoon-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From cziege...@apache.org
Subject cvs commit: xml-cocoon2/xdocs contrib.xml
Date Thu, 16 Aug 2001 10:03:15 GMT
cziegeler    01/08/16 03:03:15

  Modified:    xdocs    contrib.xml
  Log:
  [patch] contrib.xml - new sections CVS overview and dev procedure
  Submitted by: David Crossley [crossley@indexgeo.com.au]
  
  Revision  Changes    Path
  1.6       +214 -12   xml-cocoon2/xdocs/contrib.xml
  
  Index: contrib.xml
  ===================================================================
  RCS file: /home/cvs/xml-cocoon2/xdocs/contrib.xml,v
  retrieving revision 1.5
  retrieving revision 1.6
  diff -u -r1.5 -r1.6
  --- contrib.xml	2001/07/28 22:00:11	1.5
  +++ contrib.xml	2001/08/16 10:03:15	1.6
  @@ -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>cocoon-dev@xml.apache.org</code>
       (you may also want to join <code>xsp-dev@xml.apache.org</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:anoncvs@cvs.apache.org:/home/cvspublic login</code></li>
  +   <li>... use this password: <code>anoncvs</code></li>
  +   <li><code>cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic -z3 \</code>
  +    <br/><code>checkout -r HEAD xml-cocoon2</code></li>
  +   <li><code>cvs -d :pserver:anoncvs@cvs.apache.org:/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:anoncvs@cvs.apache.org:/home/cvspublic login</code></li>
  +   <li><code>cvs -d :pserver:anoncvs@cvs.apache.org:/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:anoncvs@cvs.apache.org:/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:anoncvs@cvs.apache.org:/home/cvspublic login</code></li>
  +   <li><code>cvs diff -u contrib.xml > $WORK/cocoon/contrib.xml.diff</code></li>
  +   <li><code>cvs -d :pserver:anoncvs@cvs.apache.org:/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>
  
  
  

----------------------------------------------------------------------
In case of troubles, e-mail:     webmaster@xml.apache.org
To unsubscribe, e-mail:          cocoon-cvs-unsubscribe@xml.apache.org
For additional commands, e-mail: cocoon-cvs-help@xml.apache.org


Mime
View raw message