diff --git a/devel/contributors.rst b/devel/contributors.rst index 33e689e4e..6af18107c 100644 --- a/devel/contributors.rst +++ b/devel/contributors.rst @@ -3,7 +3,7 @@ Contributor's Guide =================== -See below for selection of some of the more common contribution guidelines +See below for selection of some of the more common contribution guidelines maintained directly in `Zeek wiki `_. @@ -31,3 +31,83 @@ 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. + +.. rubric:: Workflow: Zeek ``master`` branch regularly merged into fork + +If Zeek's master branch is regularly merged into the fork, merged 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. + +.. code-block:: sh + + # Update formatting of private 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 + +.. rubric:: 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. + +.. code-block:: sh + + # 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