Submitting Patches
If you want to contribute code or documentation but you haven't been granted commit access to the source code repository 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 project team can then review your changes and apply the patch for you if it proves to be useful.
Creating a patch
Depending on what type of source code repository the project has, 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, for example:
JBAS-6176.patch
Note: 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 > JBAS-6176.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 determine 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 < JBAS-6176.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 < JBAS-6176.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 < JBAS-6176.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 < JBAS-6176.patch
This reverts the files back to their original versions.