mirror of
https://github.com/zeek/zeek.git
synced 2025-10-02 06:38:20 +00:00
ded98cd373
This is based on commit 2731def9159247e6da8a3191783c89683363689c from the zeek-docs repo.
111 lines
4.3 KiB
ReStructuredText
111 lines
4.3 KiB
ReStructuredText
|
|
===================
|
|
Contributor's Guide
|
|
===================
|
|
|
|
See below for selection of some of the more common contribution guidelines
|
|
maintained directly in `Zeek wiki
|
|
<https://github.com/zeek/zeek/wiki#contributors>`_.
|
|
|
|
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 :doc:`README </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 <https://pre-commit.com/>`_.
|
|
We use pre-commit to manage and orchestrate formatters and linters.
|
|
- ``.clang-format``: Configuration for `clang-format
|
|
<https://clang.llvm.org/docs/ClangFormat.html>`_ for formatting C++ files.
|
|
- ``.style.yapf``: Configuration for `YAPF <https://github.com/google/yapf>`_
|
|
for formatting Python files.
|
|
- ``.cmake-format.json``: Configuration for `cmake-format
|
|
<https://github.com/cheshirekow/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, 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.
|
|
|
|
.. code-block:: sh
|
|
|
|
## 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
|