Clarify in the docs what belongs in portability/

[folly.git] / folly / portability / README.md

diff --git a/folly/portability/README.md b/folly/portability/README.md
index 01e97e7aa217c1ce2616e3c2f02b7258607b91b1..d84833f5691d710cea7eb3f7cacfe1c60639851e 100644 (file)
--- a/folly/portability/README.md
+++ b/folly/portability/README.md
@@ -10,3 +10,12 @@ They are not intended to help you build your programs on these platforms.
 They are, and will remain, undocumented. They are, and will remain, subject to
 rapid, immediate, and drastic changes - including full rewrites and merciless
 deletions - without notice.
+
+Note that before adding a new file to this directory you should determine
+whether the API you are adding is a portability header or just a platform
+dependent implementation detail. Only portability headers belong in this
+directory. A portability header is defined as a header that provides the exact
+API of some platform or configuration that is not available on all platforms.
+If the API being added does not already exist on at least one of the platforms
+Folly supports, then it is an implementation detail, and does not belong in
+this directory.