Clang-tidy: Document the workflow

diff --git a/.github/scripts/git-filter.py b/.github/scripts/git-filter.py
index d1206cd65a6a42664504170803729b2bacd908b1..32b4fd469128548629400a23dab7ffc3c9266369 100755 (executable)
--- a/.github/scripts/git-filter.py
+++ b/.github/scripts/git-filter.py
@@ -42,6 +42,12 @@ def main():
     diff = sys.stdin.read()
     patch_set = unidiff.PatchSet(diff)
     for patch in patch_set:
+        # We have to deal with several possible cases for input files, as shown by git:
+        # - in ext/: ext/lmdb-safe/lmdb-safe.cc
+        # - in modules/: modules/lmdbbackend/lmdbbackend.cc
+        # - files that live in the dnsdist or rec dir only: pdns/dnsdistdist/dnsdist-dnsparser.cc or pdns/recursordist/rec-tcp.cc
+        # - files that live in pdns/ and are used by several products (but possibly not with the same compilation flags, so
+        #   it is actually important that they are processed for all products: pdns/misc.cc
         path = Path(patch.path)
         if product == 'auth':
             path = Path(cwd).joinpath(path)

diff --git a/.github/workflows/codeql-analysis.yml b/.github/workflows/codeql-analysis.yml
index f4bae95a42f0aa7ecf78297b89a09ee4139bd116..3836440a34680602049f206bdad844427b753a35 100644 (file)
--- a/.github/workflows/codeql-analysis.yml
+++ b/.github/workflows/codeql-analysis.yml
@@ -9,6 +9,19 @@ on:
 permissions: # least privileges, see https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#permissions
   contents: read
 
+# clang-tidy fun:
+# We need to invoke clang-tidy from the correct directory, the one the product was compiled in, so that we get the correct include paths.
+# This means the root for the auth, pdns/recursordist for the rec and pdns/dnsdistdist for dnsdist
+# It is important that files that are used by more than one product are processed by all the products using them
+# because they might have difference compilation flags.
+# We have to use our own clang-tidy-diff.py because the line-filter flag only supports file names, not paths.
+# Finally the GH annotations that we generate from clang-tidy.py, have to be relative to the path in the git repository, so we need to
+# follow symlinks.
+# How does that work? We use git diff to get the list of diffs, and git-filter.py to get the right folder depending on the product.
+# Then we call clang-tidy-diff.py, which invokes clang-tidy on the correct file, deducing the line numbers from the diff, and
+# merging the results for all processed files to a YAML file. Finally clang-tidy.py converts the YAML output to GitHub annotations
+# (GitHub only supports 10 of these per job, the rest are not displayed) and to GitHub markdown step summary (which has no such limits).
+
 jobs:
   analyze:
     name: Analyze