[libcxx-commits] [libcxx] [libc++] Stabilize transitive includes for C++23 (PR #134143)

[Nikolas Klauser via libcxx-commits]

================
@@ -33,21 +34,31 @@ newer version of the Standard. Libc++ also reserves the right to remove
 transitive includes at any other time, however new language versions will be
 used as a convenient way to perform bulk removals of transitive includes.
 
-For libc++ developers, this means that any transitive include removal must be
-guarded by something of the form:
+However, libc++ intends not to gratuitously break users on stable versions of
+the Standard. Hence, we intend to maintain backwards compatibility of the
+declarations we provide in a header, within reason. For libc++ developers, this
+means that any transitive include removal of a public header must be guarded by
+something of the form:
 
 .. code-block:: cpp
 
-   #if !defined(_LIBCPP_REMOVE_TRANSITIVE_INCLUDES) && _LIBCPP_STD_VER <= 20
+   #if !defined(_LIBCPP_REMOVE_TRANSITIVE_INCLUDES) && _LIBCPP_STD_VER <= 23
    #  include <algorithm>
    #  include <iterator>
    #  include <utility>
    #endif
 
-When users define ``_LIBCPP_REMOVE_TRANSITIVE_INCLUDES``, libc++ will not
-include transitive headers, regardless of the language version. This can be
-useful for users to aid the transition to a newer language version, or by users
-who simply want to make sure they include what they use in their code.
+Occasionally, private headers may also be included transitively for backwards
+compatibility in the same manner.
+
+When users define ``_LIBCPP_REMOVE_TRANSITIVE_INCLUDES``, libc++ will not include
+transitive headers, regardless of the language version. This can be useful for users
+to aid the transition to a newer language version, or by users who simply want to
+make sure they include what they use in their code.
----------------
philnik777 wrote:

We should mention that this is not stable. (And maybe consider adding a stable version of it so people can migrate?)

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