Lately I’ve been thinking about effects of our policies on users – specifically, them needing to litter their code with if sys.version_info ≶…: or ifdef Py_HEX_VERSION ≶… to avoid warnings for their users.
If we don’t want to make them do that, but also want to remove old API eventually, and don’t want a massively breaking “4.0”, the process for API we’re in no rush to get rid of it could be:
- Leave old API be until the last version without a replacement goes EOL.
- Then, turn on
DeprecationWarningand schedule removal – perhaps in another decade or so.
We’d need to keep a list. We kinda already do, in What’s New, but something more directly usable by linters would be better.
That’s Soft deprecated. R also has superseded, which sounds pretty useful:
A superseded function has a known better alternative, but the function itself is not going away . A superseded function will not emit a warning (since there’s no risk if you keep using it), but the documentation will tell you what we recommend instead.
(Ideally there’d be an easy way for linters to flag these in new code…)
And defunct, which also sounds useful:
Defunct comes after deprecated. In most cases, a deprecated function will eventually just be deleted. For very important functions, we’ll instead make the function defunct, which means that function continues to exist but the deprecation warning turns into an error. This is more user-friendly than just removing the function because users will get a clear error message explaining why their code no longer works and how they can fix it.
I imagine the API still has docs entry, so old URLs and cross-references work, but the description has been replaced by porting instructions.
I love that idea.
Speaking of docs, I also like MDN icons (see e.g. the ToC sidebar for Document), as a compact way to flag the status in overviews:
= deprecated
= non-standard/implementation-specific
= experimental/unstable