| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> |
| <html> |
| <head> |
| <META http-equiv="Content-Type" content="text/html; charset=UTF-8"> |
| <title>How to Prepare a Patch</title> |
| <link href="http://purl.org/DC/elements/1.0/" rel="schema.DC"> |
| <meta content="David Crossley" name="DC.Creator"> |
| </head> |
| <body> |
| |
| |
| <h1>Overview</h1> |
| |
| |
| <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. <span class="codefrag">*.xml, *.java, *.txt</span> |
| |
| </p> |
| |
| |
| |
| <h1>Intended Audience</h1> |
| |
| <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> |
| |
| |
| |
| <h1>Prerequisites</h1> |
| |
| <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 <span class="codefrag">'cvs checkout cocoon-2.1'</span> |
| (see <a class="external" href="http://cocoon.apache.org/community/contrib.html#cvshowto">CVS Usage Precis</a>). |
| 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 <span class="codefrag">'cvs diff -u'</span> command. |
| </li> |
| |
| </ul> |
| |
| |
| |
| |
| <h1>Steps</h1> |
| |
| <p> |
| Here is how to proceed. |
| </p> |
| |
| |
| <h2>1. Understand what a patch is</h2> |
| <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: <span class="codefrag">diff</span>. |
| </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> |
| <pre class="code"> |
| Index: contrib.xml |
| =================================================================== |
| RCS file: /home/cvspublic/cocoon-2.1/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 |
| </pre> |
| <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> |
| |
| |
| <h2>2. Modify your document and ensure consistency</h2> |
| <p> |
| Let us now go though the process of preparing that patch. |
| Go ahead and edit your local copy of the document at |
| <span class="codefrag">$COCOON_HOME/src/documentation/xdocs/contrib.xml</span> |
| |
| </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 <span class="codefrag">build docs</span> to be sure that links are not broken and that |
| the new document is presented as you intend it to be. |
| </p> |
| |
| |
| <h2>3. Get ready</h2> |
| <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> |
| |
| |
| <h2>4. Generate the differences</h2> |
| <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> |
| <pre class="code"> |
| cd src/documentation/xdocs |
| cvs diff -u contrib.xml > $WORK/cocoon/patch/contrib.xml.diff |
| </pre> |
| |
| |
| <h2>5. Pack it up</h2> |
| <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. <span class="codefrag">my-patch.tar.gz</span> or <span class="codefrag">my-patch.zip</span> |
| |
| </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> |
| <pre class="code"> |
| +---$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 |
| | | |
| </pre> |
| |
| |
| <h2>6. Describe the patch</h2> |
| <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> |
| |
| |
| <h2>7. Submit via Bugzilla</h2> |
| <p> |
| To contribute your patch to a specific project, use Bugzilla - The Apache |
| Bug Database. The procedure is explained in |
| <a href="howto-bugzilla.html">How to Contribute a Patch via Bugzilla</a>. |
| </p> |
| |
| |
| |
| |
| <h1>Real World Extension</h1> |
| |
| <h2>Multiple diffs in a single patch</h2> |
| <p> |
| A patchfile can contain the differences to various individual documents. |
| For example, the following command does that ... |
| </p> |
| <pre class="code"> |
| cd src/documentation/xdocs |
| cvs diff -u contrib.xml userdocs/concepts/sitemap.xml > my-patch.diff |
| </pre> |
| <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> |
| |
| |
| <h2>Other ways of obtaining source for diff comparison</h2> |
| <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 <a class="external" href="http://cvs.apache.org/viewcvs.cgi/*checkout*/cocoon-2.1/src/documentation/xdocs/contrib.xml?rev=HEAD&content-type=text/xml">relevant XML file via ViewCVS</a> |
| </li> |
| |
| <li>save the file to your local disk: <span class="codefrag">./contrib.xml.orig</span> |
| </li> |
| |
| <li>create a copy of the file: <span class="codefrag">./contrib.xml</span> |
| </li> |
| |
| <li>make your modifications and validate the XML</li> |
| |
| <li>use the "diff" command (i.e. not 'cvs diff') as follows |
| <br> |
| <span class="codefrag">diff -u contrib.xml.orig contrib.xml > patch/contrib.xml.diff</span> |
| </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 |
| (<a class="external" href="http://cocoon.apache.org/community/contrib.html">contrib.html</a>) |
| to your local disk: <span class="codefrag">./contrib.html.orig</span> |
| </li> |
| |
| <li>create a copy of the file: <span class="codefrag">./contrib.html</span> |
| </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> |
| <span class="codefrag">diff -u contrib.html.orig contrib.html > patch/contrib.html.diff</span> |
| </li> |
| |
| <li>proceed as for Step 5.</li> |
| |
| </ul> |
| |
| |
| |
| <h1>Tips</h1> |
| |
| <ul> |
| |
| <li>Please review your diffs before you submit your patch to Bugzilla</li> |
| |
| </ul> |
| |
| |
| |
| |
| <h1>References</h1> |
| |
| <ul> |
| |
| <li> |
| The UNIX manual pages '<span class="codefrag">man diff</span>' and '<span class="codefrag">man patch</span>'. |
| </li> |
| |
| <li> |
| CVS usage information is at |
| <a class="external" href="http://www.cvshome.org/">www.cvshome.org</a> and your local |
| '<span class="codefrag">info cvs</span>' pages or '<span class="codefrag">man cvs</span>' pages or user |
| documentation. This includes guidance about using <span class="codefrag">cvs diff -u</span> |
| |
| </li> |
| |
| </ul> |
| |
| |
| |
| </body> |
| </html> |