crossley 02/05/26 02:03:25
Modified: src/documentation/xdocs/howto book.xml howto-bugzilla.xml
index.xml
Added: src/documentation/xdocs/howto howto-patch.xml
Log:
Added new document "How to Prepare patch".
Revision Changes Path
1.3 +1 -0 xml-cocoon2/src/documentation/xdocs/howto/book.xml
Index: book.xml
===================================================================
RCS file: /home/cvs/xml-cocoon2/src/documentation/xdocs/howto/book.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- book.xml 17 May 2002 12:37:26 -0000 1.2
+++ book.xml 26 May 2002 09:03:24 -0000 1.3
@@ -19,6 +19,7 @@
</menu>
<menu label="Contribution">
+ <menu-item label="Prepare patch" href="howto-patch.html"/>
<menu-item label="Bugzilla" href="howto-bugzilla.html"/>
</menu>
1.3 +7 -7 xml-cocoon2/src/documentation/xdocs/howto/howto-bugzilla.xml
Index: howto-bugzilla.xml
===================================================================
RCS file: /home/cvs/xml-cocoon2/src/documentation/xdocs/howto/howto-bugzilla.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- howto-bugzilla.xml 25 May 2002 13:25:17 -0000 1.2
+++ howto-bugzilla.xml 26 May 2002 09:03:24 -0000 1.3
@@ -4,11 +4,11 @@
<document>
<header>
<title>How to Contribute a Patch via Bugzilla</title>
- <version>0.1</version>
+ <version>0.2</version>
<authors>
<person name="David Crossley" email="[EMAIL PROTECTED]"/>
</authors>
- </header>
+ </header>
<body>
@@ -21,7 +21,7 @@
</p>
<p>
In this How-to we will concentrate on the Patch tracking capabilities of
-Bugzilla. We will explain how to create your genereal Bugzilla account,
+Bugzilla. We will explain how to create your Bugzilla account,
how to enter a patch description, and finally how to attach the actual patch
file.
</p>
@@ -46,10 +46,10 @@
Bugzilla contributors should:
</p>
<ul>
-<li>Understand what a Patch is and how to make one.
-<!-- See <link href="howto-patch.html">How to Prepare a Patch</link> -->
-See <link href="">How to Prepare a Patch</link> (Doc under development).
-Note that a new complete document is still just a "patch".
+<li>Understand what a Patch is and how to make one
+(see <link href="howto-patch.html">How to Prepare a Patch</link>).
+Note that a new complete document is still just a "patch",
+though it does need separate treatment to a normal "diff".
</li>
<li>Understand that Bugzilla is the Apache Bug Database. Bugzilla does not
distinguish between a Bug report, a Patch submission, and an Enhancement
suggestion. They are all <em>"Bugs"</em> as far as Bugzilla is concerned.
1.3 +1 -0 xml-cocoon2/src/documentation/xdocs/howto/index.xml
Index: index.xml
===================================================================
RCS file: /home/cvs/xml-cocoon2/src/documentation/xdocs/howto/index.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- index.xml 17 May 2002 12:37:26 -0000 1.2
+++ index.xml 26 May 2002 09:03:24 -0000 1.3
@@ -31,6 +31,7 @@
<s2 title="Contribution How-Tos">
<ul>
+<li><link href="howto-patch.html">How to Prepare a Patch</link></li>
<li><link href="howto-bugzilla.html">How to Contribute a Patch
via Bugzilla</link></li>
</ul>
1.1 xml-cocoon2/src/documentation/xdocs/howto/howto-patch.xml
Index: howto-patch.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN"
"../dtd/document-v10.dtd">
<document>
<header>
<title>How to Prepare a Patch</title>
<version>0.1</version>
<authors>
<person name="David Crossley" email="[EMAIL PROTECTED]"/>
</authors>
</header>
<body>
<s1 title="Overview">
<p>
A "Patch" is the set of differences between two versions of the
same file. Patches are used to send someone the exact changes that you have
made to your version of a program or a document. They can then apply that
patch to their version to merge the changes and bring their version up-to-date
with your version.
</p>
<p>
As our example we use the contribution of a simple documentation patch for
the Apache Cocoon project. The principles apply to any project and to any
type of file, e.g. <code>*.xml, *.java, *.txt</code>
</p>
</s1>
<s1 title="Intended Audience">
<p>
Anyone who wants to contribute to a project. This document addresses the
basics, so as to get new people started.
</p>
<p>
Our example describes the use of command-line tools for a UNIX system.
Other tools can be used, as long as they produce a "unified diff"
</p>
</s1>
<s1 title="Prerequisites">
<p>
Contributers should have:
</p>
<ul>
<li>The source code of the documents as a local working copy of the CVS
repository. If you are working with the current CVS HEAD then you will
have already done a <code>'cvs checkout xml-cocoon2'</code>
(see <link href="../contrib.html#cvshowto">CVS Usage Precis</link>).
However, see below for other ways of obtaining source for diff comparison.
</li>
<li>The tools with which to prepare a patch. On UNIX the "cvs"
program has the <code>'cvs diff -u'</code> command.
</li>
</ul>
</s1>
<s1 title="Steps">
<p>
Here is how to proceed.
</p>
<s2 title="1. Understand what a patch is">
<p>
A "Patch" is the set of differences between two versions of the
same file. A patch comprises one or more "diff" files. These diffs
are produced by the program of the same name: <code>diff</code>.
</p>
<p>
Here is an example of a single diff for the Cocoon Contribution page,
where we are suggesting a minor text change. Do not get frightened. These
are just human-readable instructions to the "patch" program.
</p>
<source><![CDATA[
Index: contrib.xml
===================================================================
RCS file: /home/cvspublic/xml-cocoon2/src/documentation/xdocs/contrib.xml,v
retrieving revision 1.7
diff -u -r1.7 contrib.xml
--- contrib.xml 30 Apr 2002 07:44:52 -0000 1.7
+++ contrib.xml 26 May 2002 04:08:23 -0000
@@ -208,7 +208,7 @@
to create a patch. (The commands are for Linux.)
</p>
- <s2 title="How to Establish your Local Repository">
+ <s2 title="How to Establish your Local Working Copy">
<p>
This will checkout the current copy of the master cvs repository and
]]></source>
<p>
That is a "unified diff" ... there a some lines of context on each
side of the changes. This patch is basically saying "Change the text
on line 208".
</p>
<ul>
<li>lines to be deleted are preceded with <strong>-</strong></li>
<li>lines to be added are preceded with <strong>+</strong></li>
<li>contextual lines with no leader remain the same</li>
</ul>
</s2>
<s2 title="2. Modify your document and ensure consistency">
<p>
Let us now go though the process of preparing that patch.
Go ahead and edit your local copy of the document at
<code>$COCOON_HOME/src/documentation/xdocs/contrib.xml</code>
</p>
<p>
Ensure that it is valid XML using your favourite XML editor or an external
validating parser. Please do not leave it up to the poor committer to fix
broken XML.
</p>
<p>
Run <code>build docs</code> to be sure that links are not broken and that
the new document is presented as you intend it to be.
</p>
</s2>
<s2 title="3. Get ready">
<p>
If you are using the HEAD of CVS then ensure that your working copy is
up-to-date. Of course, if you are using a previous public release version of
Cocoon, then it is already up-to-date.
</p>
</s2>
<s2 title="4. Generate the differences">
<p>
Prepare the diff file. CVS will contact the remote repository, ensure that your
working copy is up-to-date, then compare your local copy with the master repository.
</p>
<source><![CDATA[
cd src/documentation/xdocs
cvs diff -u contrib.xml > $WORK/cocoon/patch/contrib.xml.diff
]]></source>
</s2>
<s2 title="5. Pack it up">
<p>
With a patch that involves multiple separate diffs and/or new whole xml files,
then please pack them into a compressed archive,
e.g. <code>my-patch.tar.gz</code> or <code>my-patch.zip</code>
</p>
<p>
Also, if it helps to make your contribution clearer, then you might replicate
the directory structure. Only bother with this for a complex patch.
</p>
<source><![CDATA[
+---$WORK/cocoon/patch
| +---howto
| | +---book.xml.diff ........... differences to book.xml to link the 2 docs
| | +---howto-new-topic-a.xml ... a complete new document
| | +---howto-new-topic-b.xml ... a complete new document
| +---link
| | +---livesites.xml.diff
| | +---books.xml.diff
| |
]]></source>
</s2>
<s2 title="6. Describe the patch">
<p>
Prepare a brief explanation of what your patch does. Get this ready in a text
file before you go to Bugzilla. See further hints about this in the
"Description" section of the How-to Bugzilla.
</p>
<p>
What version of CVS did you patch against? Was it HEAD branch? Was it
a nightly build? Was it a public release?
</p>
</s2>
<s2 title="7. Submit via Bugzilla">
<p>
To contribute your patch to a specific project, use Bugzilla - The Apache
Bug Database. The procedure is explained in
<link href="howto-bugzilla.html">How to Contribute a Patch via Bugzilla</link>.
</p>
</s2>
</s1>
<s1 title="Real World Extension">
<s2 title="Multiple diffs in a single patch">
<p>
A patchfile can contain the differences to various individual documents.
For example, the following command does that ...
</p>
<source><![CDATA[
cd src/documentation/xdocs
cvs diff -u contrib.xml userdocs/concepts/sitemap.xml > my-patch.diff
]]></source>
<p>
However, be careful not to go overboard with this technique. Often it is
better to produce individual diffs and then pack them all into one .zip
archive. When producing multiple diffs in one patchfile, try to limit it
to one particular topic, i.e when fixing the same broken external link
in various pages, then it would be fine to produce a single diff. Consider
the committer - they will find it hard to apply your patch if it also
attempts to fix other things.
</p>
</s2>
<s2 title="Other ways of obtaining source for diff comparison">
<p>
Ideally you will prepare your patches against a CVS repository. There are
other ways to do this. They do create more work for the committers, however
it may be the only way that you can do it. We would certainly rather receive
your patch however it comes.
</p>
<p>
You could get the source document via the web interface to CVS. Here are
the steps ...
</p>
<ul>
<li>get the <link
href="http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-cocoon2/src/documentation/xdocs/contrib.xml?rev=HEAD&content-type=text/xml";>relevant
XML file via ViewCVS</link></li>
<li>save the file to your local disk: <code>./contrib.xml.orig</code></li>
<li>create a copy of the file: <code>./contrib.xml</code></li>
<li>make your modifications and validate the XML</li>
<li>use the "diff" command (i.e. not 'cvs diff') as follows
<br /><code>diff -u contrib.xml.orig contrib.xml > patch/contrib.xml.diff</code></li>
<li>proceed as for Step 5.</li>
</ul>
<p>
There is another method if all else fails. You could save the public HTML page
that was generated by Cocoon (currently static) and then prepare your diffs
against the HTML source. This is obviously much harder for the committer, and
should only ever be used for minor text edits. Here are the steps ...
</p>
<ul>
<li>save the relevant web page
(<link href="http://xml.apache.org/cocoon/contrib.html";>contrib.html</link>)
to your local disk: <code>./contrib.html.orig</code></li>
<li>create a copy of the file: <code>./contrib.html</code></li>
<li>make your modifications and view the page with your browser</li>
<li>use the "diff" command (i.e. not 'cvs diff') as follows
<br /><code>diff -u contrib.html.orig contrib.html >
patch/contrib.html.diff</code></li>
<li>proceed as for Step 5.</li>
</ul>
</s2>
</s1>
<s1 title="Tips">
<ul>
<li>Please review your diffs before you submit your patch to Bugzilla</li>
</ul>
</s1>
<s1 title="References">
<ul>
<li>
The UNIX manual pages '<code>man diff</code>' and '<code>man patch</code>'.
</li>
<li>
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. This includes guidance about using <code>cvs diff -u</code>
</li>
</ul>
</s1>
</body>
</document>
----------------------------------------------------------------------
In case of troubles, e-mail: [EMAIL PROTECTED]
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
