diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index b38fa4c42c5..2d873f76501 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -241,7 +241,7 @@ pep-0378.txt @rhettinger # pep-0384.txt pep-0385.txt @pitrou @birkenfeld # pep-0386.txt -pep-0387.txt @benjaminp +pep-0387.txt @benjaminp @vstinner # pep-0389.txt # pep-0390.txt pep-0391.txt @vsajip diff --git a/pep-0387.txt b/pep-0387.txt index 989a7cd8a9a..1915dc648c9 100644 --- a/pep-0387.txt +++ b/pep-0387.txt @@ -4,12 +4,13 @@ Version: $Revision$ Last-Modified: $Date$ Author: Benjamin Peterson PEP-Delegate: Brett Cannon -Discussions-To: https://discuss.python.org/t/pep-387-backwards-compatibilty-policy/4421 Status: Active Type: Process Content-Type: text/x-rst Created: 18-Jun-2009 -Post-History: 19-Jun-2009, 12-Jun-2020 +Post-History: `19-Jun-2009 `__, + `12-Jun-2020 `__, + `16-Jun-2023 `__ Abstract @@ -114,6 +115,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 ===========================