Preparing Patches

First, you need a local copy of the relevant repository. In the following, we’ll use the Bro repository as an example but the same applies to all the others as well.

To get your local copy, clone it:

> git clone --recursive git://git.bro-ids.org/bro
> cd bro

Then create a branch for your changes:

> git checkout -b topic/my-feature

Now you can edit the code to your liking and commit as usual.

Once done, you can prepare a patch for submission. If you have committed multiple times, make sure each commit represents a self-contained logical unit. If your change is small, everything should probably just be part of a single commit; use git rebase -i to squash multiple commits into one (see combining commits).

Make sure that your changes apply cleanly on top of the current git master; there may have been upstream changes since you cloned. To ensure that, update your local master branch and rebase your changes on top of it:

> git checkout master
> git pull
> git submodule update --recursive --init # Update submodules.
> git checkout topic/my-feature
> git rebase master

Now, create your patch:

> git format-patch master

This creates one file per commit. To submit them, create a new ticket in the Bro Issue Tracker, set its type to patch, and attach the files to it. The ticket description should have a summary of what your changes are about.

Requesting Merge From a Fork

If you’re working on a larger set of changes, or jointly with others, it may work better to fork Bro externally, like on github. Once your code is ready for merging, you can then send us a request to merge it in, as follows.

First, prepare a branch in the external repository just as you would for sending a patch, including making sure that it will merge cleanly into our master. Then create a ticket in the tracker and set its type to patch. However, instead of adding a patch as attachment, insert the repository’s complete URL and the name of the relevant branch into the ticket’s body. We’ll then fetch the commits from there directly.

Coding Guidelines

Generally, try to adapt to the existing code structure as much as possible in terms of style, indentation, etc. We don’t have many strict rules, and conventions differ across the various subprojects, so look around a bit before you start.

When working on Bro itself, please provide one or more tests written for BTest as part of your patch; add them to the existing set in testing/btest/. If your patch adds new functionality, the test(s) should make sure everything is working correctly. If it fixes an existing bug, the test should fail without your patch and pass once it’s applied.

When contributing any Bro script code, make sure it follows documentation conventions for automatically extracting comments and also scripting conventions.

License

Please note that we require (and assume) all submissions to be subject to Bro’s standard BSD-style license.

More Information

For information on how we manage Bro’s development process, including more tips and guidelines on using git, see our process page.