From d084bc88bebe75484e319e0cdbf72a656edebfa3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?L=C5=91rinc?= Date: Tue, 28 Apr 2026 19:42:37 +0200 Subject: [PATCH] doc: clarify IWYU workflow Document the CI wrapper as the reproducible IWYU entrypoint instead of suggesting ad hoc native runs. Also describe how to handle suspected false positives, explain when local `IWYU pragma` workarounds are appropriate, and add an example rationale to an existing pragma. Co-authored-by: Hennadii Stepanov <32963518+hebasto@users.noreply.github.com> Co-authored-by: Daniel Pfeifer --- doc/developer-notes.md | 18 ++++++++++++++---- src/node/blockstorage.h | 2 ++ 2 files changed, 16 insertions(+), 4 deletions(-) diff --git a/doc/developer-notes.md b/doc/developer-notes.md index e79c14ad47f..d838ddff4b0 100644 --- a/doc/developer-notes.md +++ b/doc/developer-notes.md @@ -539,22 +539,32 @@ The generated coverage report can be accessed at `build/coverage_report/index.ht The [`include-what-you-use`](https://github.com/include-what-you-use/include-what-you-use) tool (IWYU) helps to enforce the source code organization [policy](#source-code-organization) in this repository. -To ensure consistency, it is recommended to run the IWYU CI job locally rather than running the tool directly. +To reproduce the IWYU CI job locally, run: +```bash +env -i HOME="$HOME" PATH="$PATH" USER="$USER" MAKEJOBS="-j1" FILE_ENV="./ci/test/00_setup_env_native_iwyu.sh" ./ci/test_run_all.sh || echo "IWYU failed" +``` In some cases, IWYU might suggest headers that seem unnecessary at first glance, but are actually required. For example, a macro may use a symbol that requires its own include. Another example is passing a string literal to a function that accepts a `std::string` parameter. An implicit conversion occurs at the callsite using the `std::string` constructor, which makes the corresponding header required. We accept these suggestions as is. -Use `IWYU pragma: export` very sparingly, as this enforces transitive inclusion of headers -and undermines the specific purpose of IWYU. +If the provided IWYU CI job still produces a false positive, reduce it to a minimal reproducer and report it upstream. + +Use IWYU pragmas sparingly. + +Use `IWYU pragma: keep` only as a narrow workaround when needed. + +Use `IWYU pragma: associated` only when IWYU cannot infer the intended associated header. + +Use `IWYU pragma: export` very sparingly, as this enforces transitive inclusion of headers and undermines the specific purpose of IWYU. The acceptable cases for using `IWYU pragma: export` are: 1. Facade headers. For example, see [`compat/compat.h`](/src/compat/compat.h). 2. Drop-in replacement headers. For example, see [`util/time.h`](/src/util/time.h). 3. Presenting a complete interface across multiple headers. -A comment explaining the rationale is required for every use of `IWYU pragma: export`. +For IWYU pragmas, prefer adding a nearby source comment that explains why the annotation is needed. ### Performance profiling with perf diff --git a/src/node/blockstorage.h b/src/node/blockstorage.h index a081b954735..0857ba4c8a8 100644 --- a/src/node/blockstorage.h +++ b/src/node/blockstorage.h @@ -18,6 +18,8 @@ #include #include #include +// IWYU incorrectly suggests removing this header. +// See https://github.com/include-what-you-use/include-what-you-use/issues/2014. #include // IWYU pragma: keep #include #include