[libc][docs] Add a sunset policy to porting docs #168936
Conversation
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.
|
@llvm/pr-subscribers-libc Author: Michael Jones (michaelrj-google) ChangesAs discussed in the monthly meeting, update the porting docs to clarify Full diff: https://github.com/llvm/llvm-project/pull/168936.diff 3 Files Affected:
diff --git a/libc/docs/CMakeLists.txt b/libc/docs/CMakeLists.txt
index 5b89511c33bdc..68fe9fc545781 100644
--- a/libc/docs/CMakeLists.txt
+++ b/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})
diff --git a/libc/docs/porting.rst b/libc/docs/porting.rst
index e890e439f619f..a7dcca1b3a33f 100644
--- a/libc/docs/porting.rst
+++ b/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,52 @@ 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 github documentation <https://github.com/llvm/llvm-project/blob/main/.github/workflows/libc-fullbuild-tests.yml>`
+TODO: proper link.
+
+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
+----------
+
+If a target is incomplete and no progress has been made for 1 month, or if a
+target has no active maintainers, then it may be considered stale and sunset.
+Sunsetting means removing the target specific code and turning off any related
+testing. If a target has been sunset and there new maintainers are interested
+in picking it up they are encouraged to look at the git history to learn from
+the previous implementation.
diff --git a/libc/utils/docgen/docgen.py b/libc/utils/docgen/docgen.py
index 5a57987b3c51e..59cfbd54561c7 100755
--- a/libc/utils/docgen/docgen.py
+++ b/libc/utils/docgen/docgen.py
@@ -1,4 +1,4 @@
-#!/usr/bin/env python
+#!/usr/bin/env python3
#
# ====- Generate documentation for libc functions ------------*- python -*--==#
#
|
🐧 Linux x64 Test Results✅ The build succeeded and no tests ran. This is expected in some build configurations. |
libc/docs/porting.rst
Outdated
| Sunsetting | ||
| ---------- | ||
|
|
||
| If a target is incomplete and no progress has been made for 1 month, or if a |
There was a problem hiding this comment.
1 month seems too short, it's not unusual for people to take 1+ month long vacations. I'd suggest 6 months because that way it'll span one LLVM release. We should also consider first marking the target as deprecated before it's removal to give users a sufficient heads up.
There was a problem hiding this comment.
One question I have about this policy though is: can a libc backend ever be "finished?" Given that the C committee puts out releases every 6-10 years, is it possible for a backend to be stable enough that it doesn't require any maintainers until a new standards release happens?
There was a problem hiding this comment.
All libc implementation code will use libc's internal APIs, which will never ossify. All parts of libc's implementation will need to be maintained in the sense of continually modernizing with the rest of the libc implementation. The pace of change of the common portions will eventually slow down, and the pace of change of any given target support implementation will slow as that target's details stabilize and support becomes complete. So the amount of effort required of each target's maintainers will decrease and stabilize, but never reach zero.
There was a problem hiding this comment.
I agree with the idea of synchronizing this review to the LLVM release cycle to give us a useful reference point. I'd rather not have the waiting period be too long though, I don't want to still be shipping a target that's been unmaintained for a year.
My main concern is around targets that are broken or otherwise unusable. Some targets don't get much specific contribution because they don't need it (e.g. RISC-V linux). Given that we also have a CI requirement, maybe that can be a useful metric.
We can have a slow path to deprecation where if there are 0 contributions for a target between two releases we mark it as deprecated and then if there are still 0 contributions before the next release we sunset it. Then we can have a faster path where if the CI has been broken for a month we move it to unstable or otherwise non-blocking, then if nobody picks it up and fixes it in the following 3(?) months we sunset it.
That way we aren't randomly deleting stable targets for being too stable, but we also have a path to get rid of targets that aren't properly supported in a reasonable amount of time. If people agree I'll update the PR to include that.
As for if a libc backend is ever "finished" I agree with Roland that development may slow but never stop. If we let the system interface for one target freeze then that may block changes to the others for fear of breaking compatibility.
libc/docs/porting.rst
Outdated
| Sunsetting | ||
| ---------- | ||
|
|
||
| If a target is incomplete and no progress has been made for 1 month, or if a |
There was a problem hiding this comment.
This is a good way to state the firm policy, which is to say that it allows removal if someone is so inclined but does not prescribe a regimented/guaranteed schedule that will always be imposed.
It might be useful to express a slightly stronger intent, still without making a hard commitment to "it shall always be thus". For example, perhaps we want to say that the usual procedure will be that one month before an LLVM release branch point is scheduled, we will usually actively evaluate whether anything is stale and should be removed before the branch point.
6 participants
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.