PEP 387: Add Soft Deprecation section

[vstinner]

---

📚 Documentation preview 📚: https://pep-previews--3182.org.readthedocs.build/

[vstinner]

This change was discussed at: https://discuss.python.org/t/formalize-the-concept-of-soft-deprecation-dont-schedule-removal-in-pep-387-backwards-compatibility-policy/27957

[vstinner]

@pfmoore: I addressed some of your comments.

[vstinner]

For people interested about the exact implementation of SoftDeprecationWarning: I created the PR python/cpython#106142.

[vstinner]

@pfmoore: I rephrased the section. Would you mind to review the updated PR?

[vstinner]

I replaced MUST with SHOULD:

A soft deprecation can be used when using an API which must no longer be used to write new code

becomes:

A soft deprecation can be used when using an API which should no longer be used to write new code

[vstinner]

I mark this PR as a draft to prevent merging it by mistake. I will request SC approval to merge it once it will be ready.

[pfmoore]

Much better, thanks. I've suggested one minor change.

[pfmoore]

Also, note the discussion on Discourse is still ongoing - I favour the idea of removing the association between "deprecated" and "scheduled for removal", in favour of explicitly flagging things that are planned for removal.

[vstinner]

I updated the PR to no longer issue a warning.

[vstinner]

I submitted this PEP change to the Steering Council: python/steering-council#199

[vstinner]

"The SC agrees with the proposal and accepts the PEP update": python/steering-council#199 (comment)

[vstinner]

Thanks for the reviews!