[libc] [llvm] [RFC][libc] Codify header inclusion policy (PR #87017)

[Nick Desaulniers via llvm-commits]

================
@@ -186,3 +186,30 @@ We expect contributions to be free of warnings from the `minimum supported
 compiler versions`__ (and newer).
 
 .. __: https://libc.llvm.org/compiler_support.html#minimum-supported-versions
+
+Header Inclusion Policy
+=======================
+
+Because llvm-libc supports
+`Overlay Mode <https://libc.llvm.org/overlay_mode.html>`__ and
+`Fullbuild Mode <https://libc.llvm.org/fullbuild_mode.html>`__ care must be
+taken when ``#include``'ing certain headers.
+
+The ``include/`` directory contains public facing headers that users must
+consume for fullbuild mode. As such, types defined here will have ABI
+implications as these definitions may differ from the underlying system for
+overlay mode and are NEVER appropriate to include in ``libc/src/`` without
+preprocessor guards for ``LLVM_LIBC_FULL_BUILD``.
+
+Consider the case where an implementation in ``libc/src/`` may wish to refer to
+a ``sigset_t``, what header should be included? ``<signal.h>``, ``<spawn.h>``,
+``<sys/select.h>``?
+
+None of the above. Instead, code under ``src/`` should ``#include
+"src/signal/sigset_t.h"`` which contains preprocessor guards on
----------------
nickdesaulniers wrote:

I've moved these to libc/hdr/ in https://github.com/llvm/llvm-project/pull/87017/commits/4e2833ab58e1d64c95cda19338370899f62d15fd , PTAL

https://github.com/llvm/llvm-project/pull/87017