-
Notifications
You must be signed in to change notification settings - Fork 30.4k
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
Document alternatives to deprecated methods #1002
Comments
IMHO we should just deprecate |
@vkurchatkin That's hostile to API users. If I come to the docs looking for |
Deprecated methods only exist so that legacy code could work. If you write new code, you should use something else. If you write code for older versions of platform you should use appropriate docs. That's the idea. Maybe a bit hostile, yeah. But still, docs for deprecated methods should be removed EVENTUALLY, but before methods themselves. |
I disagree. I actually think that the documentation should persist for a while after the command has been removed, saying, "this was here, but we deprecated it in semver major version x, we removed it in release semver major version x + n, and so now it's gone." And then perhaps remove the docs in semver major version x + n + 1. This is how Java did it, and it was almost invariably helpful, given how fast the Java APIs moved in its early life. |
@vkurchatkin the problem is that can, and will break a lot of existing packages. I'm all for removing @othiym23 I've created a PR clarifying the usage - can you take a look and let me know if this is what you had in mind? |
@othiym23 it is maybe works for Java because deprecated methods aren't supposed to be removed ever @benjamingr I'm not talking about removing it anytime soon. Just showing deprecation message |
@vkurchatkin Early on (0.8 - 1.3, roughly), methods and classes got removed all the time, and in fact Java used to move entire APIs around in the namespace tree, sometimes without a lot of warning. It's "easier" with Java because those kinds of rearrangements will cause failures at compile / build time, but creating affordances for this stuff is important if you don't want to aggravate your user community unnecessarily. |
@vkurchatkin like usually - I agree with your opinion here. Showing a deprecation message can be a huge win for |
At the moment users who want to use `fs.exists` get a warning that the method is deprecated but do not get offered an alternative in the page. This PR suggests `fs.stat` and `fs.access` as alternatives while keeping the warning about the use case in place. Fixes: #1002 PR-URL: #1007 Reviewed-By: Brian White <mscdex@mscdex.net> Reviewed-By: Christian Tellnes <christian@tellnes.no>
Currently the
fs.exists
method is deprecated (yay for io for doing this) however the documentation does not explain why it was deprecated (which is reasonable) or what to use instead (which is less desirable).I thought about making a docs PR suggesting using
fs.stat
orfs.access
but I'n not sure which to recommend or if recommending either is appropriate.Should an alternative be suggested inside the docs and if so which?
The text was updated successfully, but these errors were encountered: