Creating Patches

From BroWiki

This guide is aimed at general Bro users who intend to submit patches for inclusion into future releases. Depending on what kind of tree you are working with, there are different ways to create a patch. Given that our main development branch is now publically accessible via Subversion, it is strongly recommended to base any modifications on it.

Diffing against a Subversion checkout of the main development branch

This is easy. First, check out a copy of the branch:

 svn checkout http://svn.icir.org/bro/trunk/bro

Make changes locally in this branch. When you're done, simply run

 svn diff > my-patch.diff

from the toplevel directory of your tree, and send us the resulting file. See below for where to send it.

Diffing a release tree

If the baseline you've added your changes to is a release tarball, we suggest the following procedure:

• Rename the your working tree so that its toplevel directory name differs from that of the original tarball (e.g., by adding "-work").
• Extract the source tarball again, next to your development tree.
• Go to the directory containing the two trees you want to compare, and do one of the following:
  • Do a make distclean to put the tree into the same state as if it had just been extracted. This means you'll need to rebuild the tree after the diff, but it gets rid of all the files you do not want in your diff anyway. Then create a diff of the two trees using the following command:
    diff -urN <bro-tree-original>/ <bro-tree-work>/ > changes.diff
    This creates a unified diff (-u) for better readability, proceeds recursively through the tree (-r), andtreats files that only exist in one of the trees as empty in the other (-N).
  • Alternatively, if you want to keep your working tree intact, you need to ask diff to exclude everything that is generated (executables, parser code, .o's etc). To do so, grab a copy of the latest version of the dontdiff-bro.txt file from here. This file contains patterns for all files that are generated from other files in the tree or that are otherwise irrelevant. Then create the diff using
    diff -urN -X dontdiff-bro.txt <bro-tree-original>/ <bro-tree-work>/ > changes.diff

Submitting your patch, a.k.a. the road to fame

First please inspect your patch to make sure it really only contains the relevant changes. Then, give your patch file a meaningful name and submit it as an email attachment to the list at bro@bro-ids.org. Please do not send it inline in your email unless you are certain that line-wrapping won't garble your patch.