Submitting Patches

If you want to contribute code or documentation and you're not a member of a project team then you need to submit a patch. A patch is simply a file that contains the differences between one or more original files and their modified versions. The team can then review your changes and apply the patch on your behalf if it proves to be useful.

Creating a patch

Depending on what type of source code repository your project uses, you will need to use one of the following diff based commands:

cvs diff

svn diff

Both these commands compare one or more files in your local working copy with their latest versions in the repository and output the differences.

To compare a single file simply append the filename to the command:

cvs diff Example.java

svn diff Example.java

For multiple files, possibly in different directories, simply run the command from a common parent directory. For example if you're using Subversion and you've made changes to files Rocket.java and Balloon.java in the following directory structure:

com/
    flyaway/
        powered/
            Rocket.java
        nonpowered/
            Balloon.java

Then you would issue the following command from the flyaway directory to output the differences to both files:

svn diff

Using redirection you could then capture this output to create a patch file:

svn diff > bugFix23.patch

It helps to give the patch a meaningful name so that its purpose can be easily identified. Typically this will be the same name as a corresponding issue in the issue tracking system. You don't have to use the .patch suffix but it is conventional to do so.

Patch Format

Because patches are created using utilities based on the diff program, they can often be produced in a number of different formats. The most convenient format to use for readability is called Unified format. It is the only one available when using Subversion's diff command. The CVS diff command produces 'normal' format by default but you can change this to Unified format by supplying the '-u' flag:

cvs diff -u > bugFix23.patch

You can also supply a '-c' flag to produce Context format if you like. This is also easy to read but Unified format is preferred. Remember that the project team will review your patch before it is applied so it helps to make it as readable as possible.

Submitting a Patch

The best way to submit a patch is to attach it to a corresponding issue in the Issue Tracking system. This helps to keep things organized and allows the project team to find out more about the reasons for the changes from the issue details.

Applying a Patch

The project team uses the patch utility to apply a patch against a local working copy of the source code. If the patch contains changes to a single file then the filename will be specified as follows:

patch Example.java < bugFix23.patch

Otherwise if the patch contains changes to multiple files then the utility should be run from the same directory that was used to create it:

cd com/flyaway
patch -p0 < bugFix23.patch

In this case the names of the files to change are found from within the patch file and the '-p' flag is used to indicate that we are in the same directory that the patch was created in. If you are applying the patch from a different directory then you can supply a different number to change the paths accordingly. For example if we created the patch in the com directory then the filenames inside the patch would be:

flyaway/powered/Rocket.java
flyaway/unpowered/Balloon.java

To apply the patch from the flyaway directory, one level below the com directory, we would use 'patch -p1 < bugFix23.patch' to interpret the filenames as:

powered/Rocket.java
unpowered/Balloon.java

Unapplying a Patch

If something goes wrong then the changes can always be reversed by using the '-R' flag:

patch -p0 -R < bugFix23.patch

This reverts the files back to their original versions.