bpo-43795: Document stable_abi.txt format and contents (GH-29956)

Also mention that removals generally aren't allowed.

Author: encukou

Misc/stable_abi.txt

@@ -10,6 +10,46 @@
 # and PC/pythonXYstub.def
 
 
+# The current format is a simple line-based one with significant indentation.
+# Anything after a hash is a comment.
+
+# There are these kinds of top-level "items":
+# - struct: A C struct. Currently this file does not distinguish between:
+#   - opaque structs, which the Limited API only handles via pointers
+#     (so these can change at any time)
+#   - structs where only certain members are part of the stable ABI (e.g.
+#     PyObject)
+#   - structs which must not be changed at all (e.g. PyType_Slot, which is
+#     fully defined and used in arrays)
+# - function: A function that must be kept available (and exported, i.e. not
+#   converted to a macro).
+# - const: A simple value, defined with `#define`.
+# - macro: A preprocessor macro more complex than a simple `const` value.
+# - data: An exported object, which must continue to be available but its exact
+#   value may change.
+# - typedef: A C typedef which is used in other definitions in the limited API.
+#   Its size/layout/signature must not change.
+
+# Each top-level item can have details defined below it:
+# - added: The version in which the item was added to the stable ABI.
+# - ifdef: A feature macro: the item is only available if this macro is defined
+# - abi_only: If present, the item is not part of the Limited API, but it *is*
+#   part of the stable ABI. The item will not show up in user-facing docs.
+#   Typically used for:
+#   - private functions called by public macros, e.g. _Py_BuildValue_SizeT
+#   - items that were part of the limited API in the past, and must remain part
+#     of the stable ABI.
+#   - a combination of the above (functions that were called by macros that
+#     were public in the past)
+
+# Removing items from this file is generally not allowed, and additions should
+# be considered with that in mind. See the devguide for exact rules:
+#    https://devguide.python.org/c-api/#limited-api
+
+# User-facing docs are at:
+#    https://docs.python.org/3/c-api/stable.html#stable
+
+
 # Mentioned in PEP 384:
 
 struct PyObject

Tools/scripts/stable_abi.py

@@ -174,6 +174,7 @@ def raise_error(msg):
             parent.abi_only = True
         else:
             raise_error(f"unknown kind {kind!r}")
+            # When adding more, update the comment in stable_abi.txt.
         levels.append((entry, level))
     return manifest