PEP 387: Backwards Compatibility Policy updates/clarifications (#2931)

Approved in: https://discuss.python.org/t/22042/9

Author: encukou

pep-0387.txt

@@ -67,6 +67,8 @@ be removed at any time in any way.  These include:
   types that are prefixed by "_" (except special names).
 
 - Anything documented publicly as being private.
+  Note that if something is not documented at all, it is *not*
+  automatically considered private.
 
 - Imported modules (unless explicitly documented as part of the public
   API; e.g. importing the ``bacon`` module in the ``spam`` does not
@@ -123,22 +125,35 @@ several releases:
    appropriate SIG.  A PEP or similar document may be written.
    Hopefully users of the affected API will pipe up to comment.
 
-2. Add a warning.  If behavior is changing, the API may gain a new
+2. Add a warning to the current ``main`` branch.
+   If behavior is changing, the API may gain a new
    function or method to perform the new behavior; old usage should
    raise the warning.  If an API is being removed, simply warn
    whenever it is entered.  ``DeprecationWarning`` is the usual
    warning category to use, but ``PendingDeprecationWarning`` may be
    used in special cases where the old and new versions of the API will
-   coexist for many releases [#warnings]_. Compiler warnings are also
-   acceptable. The warning message should include the release the
-   incompatibility is expected to become the default and a link to an
-   issue that users can post feedback to.
+   coexist for many releases [#warnings]_.  The warning message should
+   include the release the incompatibility is expected to become the
+   default and a link to an issue that users can post feedback to.
+
+   For C API, a compiler warning generated by the ``Py_DEPRECATED`` macro
+   is also acceptable.
 
 3. Wait for the warning to appear in at least two minor Python
    versions of the same major version, or one minor version in an older
-   major version (e.g. for a warning in Python 3.10, you either wait
+   major version (e.g. for a warning in Python 3.10.0, you either wait
    until at least Python 3.12 or Python 4.0 to make the change).
-   It's fine to wait more than two releases.
+
+   It's fine to wait more than two releases, for example:
+
+   - If the expected maintenance overhead and security risk of the
+     deprecated behavior is small (e.g. an old function is reimplemented
+     in terms of a new, more general one), it can stay indefinitely
+     (or until the situation changes).
+
+   - If the deprecated feature is replaced by a new one, it should
+     generally be removed only after the last Python version
+     *without* the new feature reaches end of support.
 
 4. See if there's any feedback.  Users not involved in the original
    discussions may comment now after seeing the warning.  Perhaps