Add developer documentation on how to reformat long-lived forks

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
 <https://github.com/zeek/zeek/wiki#contributors>`_.
 
@@ -31,3 +31,81 @@ 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