Ask questionsHandle deprecation in a standard and consistent way?
We have a couple things deprecated and pending removal in the future.
Can we have a standard and consistent methodology to handle deprecation and removal?
What we have now:
warnings.warn(..., DeprecationWarning)when it's been called.
MetadataWrapper, and other metadata related classes were moved to
libcst.metadatabut there were still available in
libcstfor backward compatibility.
ExtSliceis deprecated and we have inline comments in the code.
BasicPositionProviderare about to be deprecated in https://github.com/Instagram/LibCST/pull/114
warnings.warn(..., DeprecationWarning) seems to be a widely adopted way to warn on deprecation. Can we try to use it on all cases? For class deprecation, we don't want to just subclass since that may require lots of other changes to make existing callsite/type-checking work. Can we somehow have a helper to wrap all all methods in a class to call
There are more things we can do, e.g. add the deprecation warning to readthedoc docs, so reader see it. Or explicitly declare the target version that deprecated things will be removed.
There are deprecation packages provides a
@deprecation to make all those easier:
Some projects put all deprecated things together in a doc for tracking, e.g. https://django.readthedocs.io/en/1.5.x/internals/deprecation.html https://github.com/numpy/numpy/issues/11521 This is more like a nice to have to me.
Answer questions bgw
I've seen a lot of projects use their changelog (and by extension, the github releases page) for declaring deprecations.