-
Notifications
You must be signed in to change notification settings - Fork 182
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Handle deprecation in a standard and consistent way? #116
Comments
Any sort of explicit warning we can give to developers well in advance of removal is good. I am not sure I have any opinions on I think you are right that we need some semi-formal deprecation documentation. I was proposing to @bgw that we have a document at the root called |
I've seen a lot of projects use their changelog (and by extension, the github releases page) for declaring deprecations. |
Ooh, yeah that's not a bad place to put things as well. Especially once we actually drop support for old features. |
To the extent there's a "standard approach," it's to document things in changelog / release notes (as well as the reference documentation for the affected items), and then if possible also The |
Circle back on this, we already have to many things deprecated but the deprecation process wasn't standardized. It looks messy to me. |
What are we solving here? We have a deprecation strategy: Things get deprecated on a minor release bump (such as 0.2.x -> 0.3.0) which has not happened yet. Adding a library won't help that, and we already have a record of deprecations in the changelog. Many of the things deprecated can't be decorated, and can only be documented with docstrings. Its unclear what adding another layer does for us in this case. |
Using the library is to make the deprecation documentation easier. |
The way we handle it currently is adding |
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:
BaseAssignment.accesses
callswarnings.warn(..., DeprecationWarning)
when it's been called.BatchableMetadataProvider
,MetadataWrapper
, and other metadata related classes were moved tolibcst.metadata
but there were still available inlibcst
for backward compatibility.ExtSlice
is deprecated and we have inline comments in the code.SyntacticPositionProvider
andBasicPositionProvider
are about to be deprecated in Rename position provider classes #114The
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 callwarnings.warn(..., DeprecationWarning)
?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
numpy/numpy#11521
This is more like a nice to have to me.
The text was updated successfully, but these errors were encountered: