Comments (8)
I've seen a lot of projects use their changelog (and by extension, the github releases page) for declaring deprecations.
from libcst.
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 warnings.warn(..., DeprecationWarning)
versus @deprecated
. They both seem to have their advantages and assumptions.
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 DEPRECATION
which lists our policy and things slated for deprecation as well as recommended alternatives. Some day in the future, we can also list a command to run which uses LibCST codemod capabilities to auto-upgrade code, but that's not currently possible. I like the idea of having a deprecation section in the readthedocs, because its a perfect place to list each individual deprecation as well as example code and links to the docs for what to use instead. I would assume we can do this in addition to a DEPRECATION
file or similar. Maybe we want to just update the README
with a Deprecation section close to the Future section?
from libcst.
Ooh, yeah that's not a bad place to put things as well. Especially once we actually drop support for old features.
from libcst.
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 warnings.warn(DeprecationWarning)
at runtime.
The deprecation
library providing the @deprecated
decorator I hadn't seen before, seems like just a wrapping around warnings
with some bells and whistles.
from libcst.
Circle back on this, we already have to many things deprecated but the deprecation process wasn't standardized. It looks messy to me.
Can we start using the deprecation library to add deprecated_in
, removed _in
and fail_if_not_removed
in the code? The library wrapped Python warnings helper and automatically update the docstring (so the deprecation versions show up in Sphinx doc). It also automatically fails tests when we upgrade to target version but forget to remove the deprecated functions.
from libcst.
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.
from libcst.
Using the library is to make the deprecation documentation easier.
Current the deprecated things weren't explicitly say they'll be removed in the version of 0.3.0.
The deprecation library can help us add an explicitly removal version in documents for user and raised exception when we already upgrade to new version but didn't remove them.
We can also do that manually but that's more repetitive.
from libcst.
The way we handle it currently is adding deprecated
in comment and documentation.
Then clean them up in the next major version release.
It's simple and works ok since we don't have many to deprecate.
from libcst.
Related Issues (20)
- ParserSyntaxError for "unmatched ']'" faults wrong location
- AttributeError: module 'libcst' has no attribute '_InverseOf'
- Issue with `whitespace_after_*` not fixable HOT 2
- MaybeSentinel not dataclass
- Implement PEP 696 (defaults for type params) HOT 3
- pyright + `__or__` in generic type annotations gives unknown type HOT 1
- Python 3.13.0b1: Segmentation fault when running tests HOT 2
- Indentation wart when removing an Arg from a Call - is whitespace being represented in the right place? HOT 3
- `ApplyTypeAnnotationsVisitor` does not respect `overwrite_existing_annotations` for attributes
- CST validation error on multiline match-case-if blocks
- Failing to build wheel HOT 1
- Accessing .code attribute fails with "TypeError: CSTNode._codegen() missing 1 required positional argument: 'state'" HOT 3
- Importable libcst.tests.pyre
- [support] running test suite doesnโt find libcst.native HOT 2
- Recursion depth exceeded when applying MetadataWrapper on a very long concatenated string HOT 2
- test_parse_error for native parser HOT 1
- [Windows, Mac, Linux in future] Can't use call_if_inside/call_if_not_inside matcher decorators with multiprocessing
- Warnings persist in Context HOT 2
- Link https://libcst.me/ in the docs? HOT 1
- No mute option for reels
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. ๐๐๐
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google โค๏ธ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from libcst.