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.

If your patch is 5 or more lines long then it's important that you sign a Contributor License Agreement (CLA) to established the terms and conditions of your contribution before it can be accepted. This will either be an 'Individual Contributor Agreement' if you own the copyright or a 'Corporate Contributor Agreement' if the company you work for owns the copyright. Please check before signing.

 

If you don't sign a CLA then you will be deemed to be giving Red Hat Inc. and/or its affiliates and the JBoss Community "a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare derivative works of, publicly display, publicly perform, sublicense, and distribute the contributor's contribution and such derivative works".

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.