[libc++][doc] Improve contributor documentation.

[Mordante]

Summary

Shorty before branching LLVM 13 a new CMake option was added. This
option LIBCXX_ENABLE_INCOMPLETE_FEATURES lacks the contributor
documentation. This patch rectifies that issue.

[ldionne]

LGTM with a few suggestions!

libcxx/docs/Contributing.rst

73–74

75

84

[Mordante]

Thanks for the review.

libcxx/docs/Contributing.rst

73–74

I only change a C++ Standard to the a C++ Standard. In the view of ISO there's only one standard.

[• Quuxplusone]

libcxx/docs/Contributing.rst

73–74

There is only one Standard, but there have been many Standards over the past few years. If we're going to split hairs, there's no such thing as "a Standard that has not yet been ratified," because before it's been ratified it's not a Standard yet — merely a draft. ;)

Anyway, I'd take Louis's wording with one minor tweak to the grammatical placement of yet. Also I'm ambivalent as to whether the indicated word should be or or nor:

Libc++ makes no guarantees about the implementation status [n]or the ABI stability
of features that have not yet been ratified in a C++ Standard. After the C++ Standard
is ratified, libc++ promises a conforming and ABI-stable implementation.

101

``libcxx/include/foo``: The file should include ``<version>`` and then guard the feature with an ``ifdef``.

Throughout, I recommend giving full paths. You currently say libcxx/include/__config_site.in (full path) but only include/foo (partial path); which means I'm not sure whether CMakeLists.txt on line 89 is a full path or not.
I also recommend using punctuation: somefile: Do something., not somefile do something.

109

// Make sure all feature-test macros are available.

111

// Enable the contents of the header only when libc++ was built with LIBCXX_ENABLE_INCOMPLETE_FEATURES.

[Mordante]

I addressed the issues in rGd2bc4fa3c70ad9dd1723b2e75c9059c5db2052cf.

libcxx/docs/Contributing.rst

73–74

I still like the better, so I keep that.
I have a slight preference for the or over the nor.
I moved the yet as you suggested.

101

Seems libcxx/include/__config_site.in is the only full path, the others are all relative. I changed them all to full paths.

109

Since this document describes the current implementation, I applied this change here and in <format> and <ranges>.

111

Since this document describes the current implementation, I applied this change here and in <format> and <ranges>.

libcxx/docs/Contributing.rst

 Apple.  If you don't have access to one of these platforms, you can download an
 updated list from the failed build at
 `Buildkite <https://buildkite.com/llvm-project/libcxx-ci>`__.
 Look for the failed build and select the ``artifacts`` tab. There, download the
 abilist for the platform, e.g.:
 
 * C++20 for the Linux platform.
 * MacOS C++20 for the Apple platform.
+
+Working on large features
+=========================
+
+Libc++ makes no guarantees about the implementation status or the ABI stability
+of features that have not been ratified in the C++ Standard yet. After the C++
+Standard is ratified libc++ promises a conforming and ABI-stable
+implementation. When working on a large new feature in the ratified version of
+the C++ Standard that can't be finished before the next release branch is
+created, we can't honor this promise. Another reason for not being able to
+promise ABI stability happens when the C++ Standard committee retroactively
+accepts ABI breaking papers as defect reports against the ratified C++
+Standard.
+
+When working on these features it should be possible for libc++ vendors to
+disable these incomplete features, so they can promise ABI stability to their
+customers. This is done by the CMake option
+``LIBCXX_ENABLE_INCOMPLETE_FEATURES``. When start working on a large feature
+the following steps are required to guard the new library with the CMake
+option.
+
+* ``CMakeLists.txt`` add
+
+  .. code-block:: cmake
+
+    config_define_if_not(LIBCXX_ENABLE_INCOMPLETE_FEATURES _LIBCPP_HAS_NO_INCOMPLETE_FOO)
+
+* ``libcxx/include/__config_site.in`` add
+
+  .. code-block:: c++
+
+    #cmakedefine _LIBCPP_HAS_NO_INCOMPLETE_FOO
+
+* ``include/foo`` the contents of the file should be guarded in an ``ifdef``
+  and always include ``<version>``
+
+  .. code-block:: c++
+
+    #ifndef _LIBCPP_FOO
+    #define _LIBCPP_FOO
+
+    // Make sure all feature tests macros are always available.
+    #include <version>
+    // Only enable the contents of the header when libc++ was build with LIBCXX_ENABLE_INCOMPLETE_FEATURES enabled
+    #if !defined(_LIBCPP_HAS_NO_INCOMPLETE_FOO)
+
+    ...
+
+    #endif // !defined(_LIBCPP_HAS_NO_INCOMPLETE_FO0)
+    #endif // _LIBCPP_FOO
+
+* ``src/CMakeLists.txt`` when the library has a file ``foo.cpp`` it should only
+  be added when ``LIBCXX_ENABLE_INCOMPLETE_FEATURES`` is enabled
+
+  .. code-block:: cmake
+
+    if(LIBCXX_ENABLE_INCOMPLETE_FEATURES)
+      list(APPEND LIBCXX_SOURCES
+        foo.cpp
+      )
+    endif()
+
+* ``utils/generate_feature_test_macro_components.py`` add to ``lit_markup``
+
+  .. code-block:: python
+
+    "foo": ["UNSUPPORTED: libcpp-has-no-incomplete-foo"],
+
+* ``utils/generate_header_inclusion_tests.py`` add to ``lit_markup``
+
+  .. code-block:: python
+
+    "foo": ["UNSUPPORTED: libcpp-has-no-incomplete-foo"],
+
+* ``utils/generate_header_tests.py`` add to ``header_markup``
+
+  .. code-block:: python
+
+    "foo": ["ifndef _LIBCPP_HAS_NO_INCOMPLETE_FOO"],
+
+* ``utils/libcxx/test/features.py`` add to ``macros``
+
+  .. code-block:: python
+
+    '_LIBCPP_HAS_NO_INCOMPLETE_FOO': 'libcpp-has-no-incomplete-foo',
+
+* All tests that include ``<foo>`` should contain
+
+  .. code-block:: c++
+
+    // UNSUPPORTED: libcpp-has-no-incomplete-foo
+
+Once the library is complete these changes and guards should be removed.