Contribution Guide
The best part of open source code is that anybody can help move it forward. We appreciate any contributions to Zeek, from tiny tweaks to major parts of functionality. In the following we summarize some guidelines for making sure we will be able to integrate your code into Zeek quickly.
The process for preparing contributions depends on the size of your changes. If it's just a small fix or enhancement, go ahead and create a Pull Request on GitHub; see below for more on that.
For larger contributions (such as major new functionality, architectural improvements, or changes touching a lot of the code base), please coordinate with us upfront, ideally even before you start any work. That way, we can get a sense of what’s coming and provide you with feedback on both the functionality and the particular implementation approach you are planning to take. We may also be able to point you to prior work, or discussions, related to what you’re looking at—Zeek has been around for a long time, and many ideas have come up repeatedly over the years, even if no action has been taken yet.
As a general rule, the more buy-in you get early on, the more likely your contribution will eventually land in Zeek. We strongly recommend that you first reach out informally with a short summary of your plan, either on the Zeek development mailing list or on the Slack #development channel. If the discussion there encourages you to proceed, open a GitHub ticket to track your contribution and assign it to yourself. We suggest that you then create a more formal project proposal that sketches out the work you are planning to do, including motivation, rationale for your particular approach, and some specifics on the anticipated implementation. Put that either directly into the ticket, or on a separate page somewhere, like into a Google Doc. We’ll be happy to review and provide feedback. Experience shows that once there’s agreement on a proposal, landing something into upstream Zeek tends to go pretty smoothly.
The Zeek core developers are following the same process as well: You’ll find tickets, proposals, and discussions for what we are working on through the same channels. You’re welcome (and encouraged!) to chime in with feedback and suggestions.
We use GitHub’s Pull Requests (PRs) for all contributions. Please fork the relevant repositories on your own account, make your changes inside a branch, and then create a PR against the upstream repository. Please include a summary of your contributions inside the PR’s description, on top of any individual commit messages; and make sure to reference any GitHub issues related to your PR. Please double-check that your changes merge cleanly into the current git master branch before you create the PR; there might have been upstream changes since you forked originally. If your fork is out of sync with upstream, please rebase it on top of master first.
If your change is small, everything should probably just be part of a single commit; best to then squash your work if you had originally created multiple commits. For larger changes, however, please break your work down into smaller chunks, with each commit representing a self-contained logical unit that can be reviewed independently. Keep in mind that the easier it is to review your contribution, the quicker we’ll be able provide feedback and merge it in.
If your change spans multiple repositories (such as the main zeek/zeek one and one of its submodules), please submit a separate PR for each repository, and cross-link them in the comments. Usually there's a "main PR", in which case it's helpful to mention that one in the related PR(s). In your PRs, try to point affected submodules at the right commits/branches, so our CI can run on the entirety of the changeset. Once the PR(s) are approved, the merge masters will make sure to keep the submodules straight as they merge your work.
This blog post has great advice on composing good PRs, and here is good advice on helpful commit messages.
When we merge your contribution, we’ll credit you by name in the CHANGES file. Let us know if you have any particular wishes or constraints in that regard.
If you'd like to make a contribution to the documentation on docs.zeek.org, please submit pull requests to the zeek-docs repository and take a look at our Documentation Style and Conventions.
For smaller, single-file contributions you can complete the process entirely in the Github UI, as follows:
-
Locate the file to edit. There's a one-to-one correspondence between URL paths on docs.zeek.org and files in the zeek-docs repo. For example, the sources of https://docs.zeek.org/en/master/install.html reside in https://github.com/zeek/zeek-docs/blob/master/install.rst.
-
Enter edit mode for this file: clicking the pencil icon in the top right or hit the
ekey.
-
Make your desired changes.
-
Submit your change as a PR. At the bottom of the page, create a new branch for your contribution as suggested by Github and click "Propose changes":
-
In the next screen, you can inspect a diff of your changes. Make sure there aren't any unintended editing artifacts, and submit the PR.
-
At this point, our CI setup will verify that the documentation builds successfully and a member of our development team will pick up the PR. Thank you!
Generally, try to adapt to the existing code structure as much as possible in terms of style & idioms. The Zeek Wiki provides a collection of corresponding guidelines for contributors, including a style guide.
Please make sure to provide tests with your contribution. When working on Zeek itself, that means you should provide system-level tests using BTest and/or unit tests using doctest. If your contribution adds new functionality, add tests that ensure everything is working as expected. If it fixes an existing problem, the tests should fail without your patch and pass once it gets applied.
Please also include updates to the documentation for any user-visible changes. When contributing any Zeek script code, make sure it follows documentation conventions for automatically extracting comments. If you are unsure how/where to document your contributions, feel free to ask.
Please note that we require (and implicitly assume) all contributions to be subject to Zeek’s standard BSD-style license. Due to that liberal license, we do not require contributors to sign any explicit license agreements. We will, however, assume that you’re fine with applying our standard license headers to new files, which implies moving ownership to the project. Please let us know in advance if you are not comfortable with that.