From 0fe6fccec279f9799dfb84c36cf9033eedcc2c32 Mon Sep 17 00:00:00 2001
From: Hennadii Stepanov <32963518+hebasto@users.noreply.github.com>
Date: Fri, 13 Mar 2026 12:54:18 +0000
Subject: [PATCH] doc: Document rationale for using `IWYU pragma: export`

---
 doc/developer-notes.md | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/doc/developer-notes.md b/doc/developer-notes.md
index d8ce01c8118..399fcbd094d 100644
--- a/doc/developer-notes.md
+++ b/doc/developer-notes.md
@@ -542,6 +542,13 @@ to a function that accepts a `std::string` parameter. An implicit conversion occ
 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`.
+
 ### Performance profiling with perf
 
 Profiling is a good way to get a precise idea of where time is being spent in