[libc][docs] Add a sunset policy to porting docs (llvm#168936)

As discussed in the monthly meeting, update the porting docs to clarify
what's needed for a target and add a policy for sunsetting targets.

Author: michaelrj-google

libc/docs/CMakeLists.txt

@@ -86,7 +86,7 @@ if (SPHINX_FOUND)
 
       # docgen invocation.
       add_custom_target(${stem_rst}
-        COMMAND ${CMAKE_CURRENT_SOURCE_DIR}/../utils/docgen/docgen.py ${stem}.h >
+        COMMAND ${Python3_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/../utils/docgen/docgen.py ${stem}.h >
                 ${CMAKE_CURRENT_BINARY_DIR}/headers/${stem}.rst)
       # depend on the docgen invocation.
       add_dependencies(docs-libc-html ${stem_rst})

libc/docs/porting.rst

@@ -8,23 +8,11 @@ Bringup on a New OS or Architecture
   :depth: 4
   :local:
 
-CI builders
-===========
-
-If you are contributing a port for an operating system or architecture which
-is not covered by existing CI builders, you will also have to present a plan
-for testing and contribute a CI builder. See
-`this guide <https://llvm.org/docs/HowToAddABuilder.html>`_ for information
-on how to add new builders to the
-`LLVM buildbot <https://lab.llvm.org/buildbot>`_.
-You will either have to extend the existing
-`Linux script <https://github.com/llvm/llvm-zorg/blob/main/zorg/buildbot/builders/annotated/libc-linux.py>`_
-and/or
-`Windows script <https://github.com/llvm/llvm-zorg/blob/main/zorg/buildbot/builders/annotated/libc-windows.py>`_
-or add a new script for your operating system.
+Building the libc
+=================
 
 An OS specific config directory
-===============================
+-------------------------------
 
 If you are starting to bring up LLVM's libc on a new operating system, the first
 step is to add a directory for that OS in the ``libc/config`` directory. Both
@@ -44,7 +32,7 @@ have their own config directory.
    source tree.
 
 Architecture Subdirectory
-=========================
+-------------------------
 
 There are parts of the libc which are implemented differently for different
 architectures. The simplest example of this is the ``syscall`` function and
@@ -63,7 +51,7 @@ The libc CMake machinery looks for subdirectories named after the target
 architecture.
 
 The entrypoints.txt file
-========================
+------------------------
 
 One of the important pieces of config information is listed in a file named
 ``entrypoints.txt``. This file lists the targets for the entrypoints (see
@@ -90,7 +78,7 @@ target architectures, then multiple ``entrypoints.txt`` files will have to be
 updated.
 
 The headers.txt file
-====================
+--------------------
 
 Another important piece of config information is listed in a file named
 ``headers.txt``. It lists the targets for the set of public headers that are
@@ -103,3 +91,68 @@ bring up. The Linux config has ``headers.txt`` file listed separately for the
 config and the
 `x86_64 <https://github.com/llvm/llvm-project/tree/main/libc/config/linux/x86_64>`_
 config.
+
+
+Upstreaming
+===========
+
+Adding a target to the main LLVM-libc has some requirements to ensure that the
+targets stay in usable condition. LLVM-libc is under active development and
+without active maintenance targets will become stale and may be sunset.
+
+Maintenance
+-----------
+
+To add a target there must be one or more people whose responsibility it is to
+keep the target up to date or push it forwards if it's not complete. Those
+people are the maintainers, and they are responsible for keeping their target in
+good shape. This means fixing their target when it breaks, reviewing patches
+related to their target, and keeping the target's CI running.
+
+Maintainers are listed in libc/maintainers.rst and must follow
+`LLVM's maintainer policy <https://llvm.org/docs/DeveloperPolicy.html#maintainers>`_.
+
+CI builders
+-----------
+
+Every target needs at least one CI builder. These are used to check when the
+target breaks, and to help people who don't have access to the specific
+architecture fix their bugs. LLVM-libc has both presubmit CI on github
+and postsubmit CI on the `LLVM buildbot <https://lab.llvm.org/buildbot>`_. For
+instructions on contributing a postsubmit buildbot read
+`the LLVM documentation <https://llvm.org/docs/HowToAddABuilder.html>`_ and for
+presubmit tests read
+`the best practices <https://llvm.org/docs/CIBestPractices.html>`_
+
+The test configurations are at these links:
+ * `Linux Postsubmit <https://github.com/llvm/llvm-zorg/blob/main/zorg/buildbot/builders/annotated/libc-linux.py>`_
+ * `Windows Postsubmit <https://github.com/llvm/llvm-zorg/blob/main/zorg/buildbot/builders/annotated/libc-windows.py>`_
+ * `Fullbuild Presubmit <https://github.com/llvm/llvm-project/blob/main/.github/workflows/libc-fullbuild-tests.yml>`_
+ * `Overlay Presubmit <https://github.com/llvm/llvm-project/blob/main/.github/workflows/libc-overlay-tests.yml>`_
+
+Sunsetting
+----------
+
+Sunsetting is the process through which targets can be removed from LLVM-libc.
+If a target is broken or stale it may be sunset. It is the responsibility of the
+target's maintainers to keep it from being sunset. The target's maintainers may
+be marked inactive if their target is sunset.
+
+Broken targets are ones where the target's CI has been failing for at least
+30 days. After 30 days have passed the CI should be changed so it does not
+block commits and does not notify people when it fails. If the target remains
+broken for another 90 days it may be sunset.
+
+Stale targets are ones with no active maintainers or no contributions. If a
+target has 0 specific contributions between two major LLVM releases, or if it
+has no active maintainers, then it may be marked "deprecated" in the next major
+release. If there are still no contributions or no maintainers after the next
+major release it may be sunset.
+
+To sunset a target, all specific references to that target in the code and build
+system should be removed. All buildbots for that target should be shut down, or
+otherwise removed.
+
+To restart a target that was previously sunset, the new maintainers are
+encouraged to look at the commit(s) removing the target to provide a starting
+point.

libc/utils/docgen/docgen.py

@@ -1,4 +1,4 @@
-#!/usr/bin/env python
+#!/usr/bin/env python3
 #
 # ====- Generate documentation for libc functions  ------------*- python -*--==#
 #