Patch Submission Guide

This document describes how to submit patches for the freebXML Registry project.

What is a Patch

A patch is a file containing a listing of changes (differences) between the original source code and a modified version of that source code. Such a patch file is used to submit suggested bug fixes and other enhancements to the source code. A patch file is the format in which bugs and improvements SHOULD be submitted to the project team.

Here is a sample of what a patch file looks like:

Index: conf/log4j.properties

===================================================================

RCS file: /cvsroot/ebxmlrr/omar/conf/log4j.properties,v

retrieving revision 1.1.1.1

diff -u -r1.1.1.1 log4j.properties

--- conf/log4j.properties 24 Sep 2003 03:56:00 -0000 1.1.1.1

+++ conf/log4j.properties 20 Mar 2004 23:10:48 -0000

@@ -1,6 +1,6 @@

-log4j.rootLogger=info, stdout, R

+#log4j.rootLogger=info, stdout, R

# Use this instead for debugging:

-# log4j.rootLogger=trace, stdout, R

+x#log4j.rootLogger=trace, stdout, R



log4j.appender.stdout=org.apache.log4j.ConsoleAppender

log4j.appender.stdout.layout=org.apache.log4j.PatternLayout

  • Lines that begin with '-' are lines removed from original source

  • Lines that begin with '+' are lines added to original source

  • Additional lines are there to add context to where in the file are the changes

When to Submit a Patch

A patch may be submitted whenever someone has implemented and tested a Bug Fix or an RFE. Testing a patch requires running the test.unit target before and after the code changes for the patch to make sure that the patch does not break any code.

Who Can Submit a Patch

Any one that uses the software produced by the project can submit a patch.

How to Submit a Patch

  • Check if there is an existing Bug or RFE for the problem. If not create one (note you must first register with Source Forge and be logged into Source Forge)

  • Send an email to ebxmlrr-tech mailing list listing the URL to the Bug or RFE and stating that you are working on a patch for it. This prevents duplicated efforts.

  • Run the JUnit regression tests before you make any code changes and save the output in a file for later comparison. This gives you a baseline for which tests pass and which tests fail before your changes.

  • Optional but strongly suggested: Create a new JUnit test or update an appropriate existing JUnit test to duplicate the bug or test the RFE. Make sure the new test(s) fails prior to your code changes.

  • Make your code changes

  • Run the JUnit regression tests after you make your code changes and compare with the saved output. Make sure your changes have not made any new tests fail. Make sure that your new test(s), if any, now pass instead of fail.

  • If you have checked out project source from the CVS repository the create patch at the top level as follows:

    • If you are a team member, perform a cvs add for your new files (do NOT commit yet!). They will show in the diff thanks to the '-N' option.

    • Create one patch file for all your changes related to a particular Bug or RFE:

      cvs diff -u -N <file-1> <file-2> ... <file-n> > <patch-file-name>

    • Example (Assumes the bug or RFE id is 885459 and the file being patched is conf/log4j.properties):

      diff -u -N conf/log4j.properties > patch-885459.txt

    • If you are a team not member, remember to also attach any new files you create

    • Note that if you use a decent IDE tool such as NetBeans then it has automated tool support for creating patch files. Use Universal diff format if there is a choice offered. This is what '-u' option in 'cvs diff -u -N' specifies. The universal diff format is the preferred patch format for the project.

  • If your code is from a release that you have downloaded then create the patch as follows (assumes unix environment or cygwin on windows):

    • Make a copy of original file before modifying it with your changes

    • Create a separate patch file for each modified file using unix diff command and universal format:

      diff -u <original file> <modified file> > <patch-file-name>

    • Example (Assumes the bug or RFE id is 885459 and the file being patched is conf/log4j.properties):

      diff -u conf/log4j.properties.orig conf/log4j.properties > patch-885459.txt

    • If you send diffs for multiple files, concatenate all the diffs in a single text file before submission. Please don't produce a zip file with multiple patches.

    • Remember to also attach any new files you create

  • Update Bug or RFE page and upload your patch file.

  • Email a notice of the patch submission the ebxmlrr-team alias with subject:

    [Patch Submission] Bug 885459: Access Control design not intercepting all Actions

What Happens When You Submit a Patch

  • The patch is reviewed by the project team for correctness and quality

  • The project team decides whether to accept the patch or not and responds to the mailing list on the decision on the patch. If the patch is rejected an explanation is provided.

  • If the patch is accepted then the project team decides when the patch is to be rolled into the code base and who is the project team member responsible for it. These decisions will be communicated to the mailing list.

  • The project team member responsible incorporates the patch either AS IS or with necessary modifications.

  • The project team member responsible notifies the mailing list once the patch has been rolled into the code base

  • The project team member updates the Bug or RFE related to the patch

Applying A Patch

If you receive a patch file and trust the source then you can apply it to your src tree as follows on Unix systems and on windows systems that have cygwin or other Unix environment installed:

  • cd omar #cd to root directory:

  • patch -p0 < pmf.patch.txt #Apply the patch file

Note that you will then need to compile and may need to deploy and bounce the server.

Links