PEP 387: Add Soft Deprecation section

vstinner · vstinner · commit 53dab723660e · 2023-06-30T11:24:00.000+02:00
diff --git a/pep-0387.txt b/pep-0387.txt
@@ -114,6 +114,30 @@ Basic policy for backwards compatibility
   platforms).
 
 
+Soft Deprecation
+================
+
+A soft deprecation can be used when using an API which should no longer
+be used to write new code, but it remains safe to continue using it in
+existing code. The API remains documented and tested, but will not be
+developed further (no enhancement).
+
+The main difference between a "soft" and a (regular) "hard" deprecation
+is that the soft deprecation does not imply scheduling the removal of
+the deprecated API.
+
+Another difference is that a soft deprecation does not issue a warning:
+it's only mentioned in the documentation, whereas usually a "hard"
+deprecation issues a ``DeprecationWarning`` warning at runtime. The
+documentation of a soft deprecation should explain why the API should be
+avoided, and if possible propose a replacement.
+
+If the decision is made to deprecate (in the regular sense) a feature
+that is currently soft deprecated, the deprecation must follow the
+`Backwards Compatibility Rules`_ (i.e., there is no exception because
+the feature is already soft deprecated).
+
+
 Making Incompatible Changes
 ===========================
 
