Contributor’s Guide

See below for selection of some of the more common contribution guidelines maintained directly in Zeek wiki.

General Contribution Process

See https://github.com/zeek/zeek/wiki/Contribution-Guide

Coding Style and Conventions

See https://github.com/zeek/zeek/wiki/Coding-Style-and-Conventions

General Documentation Structure/Process

See the README file of https://github.com/zeek/zeek-docs

Documentation Style and Conventions

See https://github.com/zeek/zeek/wiki/Documentation-Style-and-Conventions

Checking for Memory Errors and Leaks

See https://github.com/zeek/zeek/wiki/Checking-for-Memory-Errors-and-Leaks

Maintaining long-lived forks of Zeek

Consistent formatting of the Zeek codebase is enforced automatically by configurations tracked in the repository. Upstream updates to these configurations can lead to formatting changes which could cause merge conflicts for long-lived forks.

Currently the following configuration files in the root directory are used:

  • .pre-commit-config.yaml: Configuration for pre-commit. We use pre-commit to manage and orchestrate formatters and linters.

  • .clang-format: Configuration for clang-format for formatting C++ files.

  • .style.yapf: Configuration for YAPF for formatting Python files.

  • .cmake-format.json: Configuration for cmake-format for formatting CMake files.

With these configuration files present pre-commit run --all-files will install all needed formatters and reformat all files in the repository according to the current configuration.

Workflow: Zeek master branch regularly merged into fork

If Zeek’s master branch is regularly merged into the fork, merge conflicts can be resolved once and their resolution is tracked in the repository. Similarly, we can explicitly reformat the fork once and then merge the upstream branch.

## Get and stage latest versions of configuration files from master.
git checkout master -- .pre-commit-config.yaml .clang-format .style.yapf .cmake-format.json

## Reformat fork according to new configuration.
pre-commit run -a

## Record reformatted state of fork.
git add -u && git commit -m 'Reformat'

# Merge in master, resolve merge conflicts as usual.
git merge master

Workflow: Fork regularly rebased onto Zeek master branch

If the target for a rebase has been reformatted individual diff hunks might not apply cleanly anymore. There are different approaches to work around that. The approach with the least conflicts is likely to first reformat the fork according to upstream style without pulling in changes, and only after that rebase on upstream and resolve potential semantic conflicts.

# Create a commit updating the configuration files.
git checkout master -- .pre-commit-config.yaml .clang-format .style.yapf .cmake-format.json
git commit -m 'Bump formatter configurations'

# With a fork branched from upstream at commit FORK_COMMIT, rebase the
# config update commit 'Bump formatter configurations' to the start of the
# fork, but do not yet rebase on master (interactively move the last patch
# to the start of the list of patches).
git rebase -i FORK_COMMIT

# Reformat all commits according to configs at the base. We use the '--exec'
# flag of 'git rebase' to execute pre-commit after applying each patch. If
# 'git rebase' detects uncommitted changes it stops automatic progress so
# one can inspect and apply the changes.
git rebase -i FORK_COMMIT --exec 'pre-commit run --all-files'
# When this stops, inspect changes and stage them.
git add -u
# Continue rebasing. This prompts for a commit message and amends the last
# patch.
git rebase --continue

# The fork is now formatted according to upstream style. Rebase on master,
# and drop the 'Bump formatter configurations' patch from the list of patches.
git rebase -i master