This page summarizes strategies for submitting patches and new functionality for inclusion into Bro. You can either fork Bro’s git repositories (using github if you want) and we’ll merge directly from there, or you can send us a patch generated by git.
The easiest way to submit patches is forking one of our git repositories. We maintain official mirrors on GitHub, or you can clone directly from the master bro.org repositories at git://git.bro.org/<repo>. To simply get copy of the complete Bro source tree from there, do:
> git clone --recursive git://git.bro.org/bro
If you fork on github, submit a pull request with your changes. Otherwise, create a ticket in our tracker and set its type to Merge Request. If your repository is publically accessible, add your repository’s URL and the name of the relevant branch to the ticket body. If your repository is not public, prepare a patch and attach that directly to the tracker ticket (see below for how to create the patch). In either case, also include a description of the changes with the ticket.
Generally, please make sure that your changes merge cleanly into the current git master. Please double-check this as there might have been upstream changes since you cloned: 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
If your changes consist of multiple commits, please make sure each one 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).
To prepare a patch to attach directly to a tracker ticket, first 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. Now, create your patch:
> git format-patch master
This creates one file per commit, which you can then attach to the ticket.
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.
Please note that we require (and assume) all submissions to be subject to Bro’s standard BSD-style license.