How to Prepare a Patch

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.

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. *.xml, *.java, *.txt

Anyone who wants to contribute to a project. This document addresses the basics, so as to get new people started.

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"

Contributers should have:

• The source code of the documents as a local working copy of the SVN repository.
• The tools with which to prepare a patch.

Here is how to proceed.

1. Understand what a patch is

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: diff.

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.

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

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".

• lines to be deleted are preceded with -
• lines to be added are preceded with +
• contextual lines with no leader remain the same

2. Modify your document and ensure consistency

Let us now go though the process of preparing that patch. Go ahead and edit your local copy of the document at $COCOON_HOME/src/documentation/xdocs/contrib.xml

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.

Run build docs to be sure that links are not broken and that the new document is presented as you intend it to be.

3. Get ready

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.

4. Generate the differences

5. Pack it up

With a patch that involves multiple separate diffs and/or new whole xml files, then please pack them into a compressed archive, e.g. my-patch.tar.gz or my-patch.zip

Also, if it helps to make your contribution clearer, then you might replicate the directory structure. Only bother with this for a complex patch.

+---$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
|   |   

6. Describe the patch

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.

What SVN revision did you patch against? Which branch? Was it an SVN snapshot? Was it a public release?

7. Submit via Jira

To contribute your patch to a specific project, use Jiraa - The Apache Bug Database. The procedure is explained in How to Contribute a Patch via Jira.

Multiple diffs in a single patch

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.

Other ways of obtaining source for diff comparison

• Please review your diffs before you submit your patch!

• The UNIX manual pages 'man diff' and 'man patch'.
• Subversion info mentioned above.