[PATCH] D146420: Document the Clang policies on claiming support for a feature

[Aaron Ballman via Phabricator via cfe-commits]

aaron.ballman created this revision.
aaron.ballman added reviewers: clang-language-wg, rsmith.
Herald added a project: All.
aaron.ballman requested review of this revision.
Herald added a project: clang.

We do not currently have this written down anywhere, and as a result, we're sometimes inconsistent with how we handle feature test macros and the feature status pages. This is an attempt to document what I understand our existing policies to be instead of defining a new policy.

Note, this is being added to the Clang internals manual because we don't have a separate document for Clang developer policies. At some point, I think we may want a standalone document for that, and this content can be moved there at that time.


Repository:
  rG LLVM Github Monorepo

https://reviews.llvm.org/D146420

Files:
  clang/docs/InternalsManual.rst


Index: clang/docs/InternalsManual.rst
===================================================================
--- clang/docs/InternalsManual.rst
+++ clang/docs/InternalsManual.rst
@@ -3268,3 +3268,39 @@
      proper visitation for your expression, enabling various IDE features such
      as syntax highlighting, cross-referencing, and so on.  The
      ``c-index-test`` helper program can be used to test these features.
+
+Feature Test Macros
+===================
+Clang implements several ways to test whether a feature is supported or not.
+Some of these feature tests are standardized, like ``__has_cpp_attribute`` or
+``__cpp_decltype``, while others are Clang extensions, like ``__has_builtin``.
+The common theme among all the various feature tests is that they are a utility
+to tell users that we think a particular feature is complete. However,
+completeness is a difficult property to define because features may still have
+lingering bugs, may only work on some targets, etc. We use the following
+criteria when deciding whether to expose a feature test macro (or particular
+result value for the feature test):
+
+  * Are there known issues with the feature that reject valid code?
+  * Are there known issues that fail to reject invalid code?
+  * Are there known crashes, failed assertions, or miscompilations?
+  * Are there known issues on a particular relevant target?
+
+If the answer to any of these is "yes", you should either not define the
+feature test macro or have very strong rationale for why the issues should not
+prevent defining it. Note, it is acceptable to define the feature test macro on
+a per-target basis if needed.
+
+When in doubt, being conservative is better than being aggressive. If we don't
+claim support for the feature but it does useful things, users can still use it
+and provide us with useful feedback on what is missing. But if we claim support
+for a feature that has significant bugs, we've eliminated most of the utility
+of having a feature testing macro at all because users are then forced to test
+what compiler version is in use to get a more accurate answer.
+
+The status reported by the feature test macro should always be reflected in the
+language support page for the feature (`C++
+<https://clang.llvm.org/cxx_status.html>`_, `C
+<https://clang.llvm.org/c_status.html>`_) if applicable. This page can give
+more nuanced information to the user as well, such claiming partial support for
+a feature and specifying details as to what remains to be done.


-------------- next part --------------
A non-text attachment was scrubbed...
Name: D146420.506565.patch
Type: text/x-patch
Size: 2518 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/cfe-commits/attachments/20230320/7d87dda5/attachment.bin>