fs: stability 3 (Stable) => Backwards compatibility is guaranteed. There was an opportunity to fix it when moving it from path to fs. But now it's too late!
Well, that's just life! On Thursday, August 23, 2012 5:12:30 PM UTC+2, Isaac Schlueter wrote: > > Scott Gonzalez posted a good link about deprecation. I copied it to a > wiki page. This is the official policy: > https://github.com/joyent/node/wiki/deprecation > > I'd accept a pull request that explains the oddness of fs.exists in > the documentation. Making it non-enumerable or removing it from the > docs is a bad idea, on further consideration. > > I'd also accept a pull request that documents all the Posix error > codes, though really, that should probably be part of the libuv > documentation. (But writing docs for libuv is a much larger pull > request.) > > > On Wed, Aug 22, 2012 at 9:49 PM, Mikeal Rogers > <[email protected]<javascript:>> > wrote: > > This suggested gained a lot of +1's so i want to talk about it a moment. > > > > I don't think it's suitable to *remove* APIs that still exist from the > docs or hide them from being enumerable. > > > > There are just too many node programs out there now and people who want > to understand existing code need to read the documentation for an API that > *is still active* should be able to find and view it and to debug that API > via test code in the repl which making non-enumerable makes annoying. > > > > This just isn't the grown up way to handle a mistake or a deprecation. > > > > We need to call out in the docs that 1) this exists and is still > available 2) it should not be used 3) why it should not be used and links > to doing things the "right" way. Pretending it doesn't exist when it still > does is like pretending we never made this mistake even though it still > works in node. Let's take responsibility for this and do what's best for > all of the existing and future users of node. > > > > -Mikeal > > > > On Aug 20, 2012, at August 20, 20128:53 AM, Tim Caswell < > [email protected] <javascript:>> wrote: > > > >> How about removing it from the docs and making it non-enumerable in > >> the fs module. Then any new developers won't know it's there unless > >> they are reading someone else's code. Or maybe in the docs simply say > >> that it shouldn't be used and is only left there so as to not break > >> old code. Also, how is this different from deprecation? > >> > >> On Sun, Aug 19, 2012 at 4:02 PM, Bert Belder > >> <[email protected]<javascript:>> > wrote: > >>> On Sunday, August 19, 2012 8:23:53 PM UTC+2, Nuno Job wrote: > >>>> > >>>>>> Maybe a note in the docs tell people that fs.stat is a better > choice? > >>>> > >>>> Good idea Mikeal. Deprecation console.error && pointing people to > >>>> fs.stat in the docs should do the trick. > >>> > >>> > >>> I don't see enough compelling reasons to deprecate it. I think a doc > >>> addition that warns people about the funky signature and the > anti-pattern > >>> would suffice. > >>> > >>> - Bert > >>> > >>> > >>> -- > >>> Job Board: http://jobs.nodejs.org/ > >>> Posting guidelines: > >>> https://github.com/joyent/node/wiki/Mailing-List-Posting-Guidelines > >>> You received this message because you are subscribed to the Google > >>> Groups "nodejs" group. > >>> To post to this group, send email to [email protected]<javascript:> > >>> To unsubscribe from this group, send email to > >>> [email protected] <javascript:> > >>> For more options, visit this group at > >>> http://groups.google.com/group/nodejs?hl=en?hl=en > >> > >> -- > >> Job Board: http://jobs.nodejs.org/ > >> Posting guidelines: > https://github.com/joyent/node/wiki/Mailing-List-Posting-Guidelines > >> You received this message because you are subscribed to the Google > >> Groups "nodejs" group. > >> To post to this group, send email to [email protected]<javascript:> > >> To unsubscribe from this group, send email to > >> [email protected] <javascript:> > >> For more options, visit this group at > >> http://groups.google.com/group/nodejs?hl=en?hl=en > > > > -- > > Job Board: http://jobs.nodejs.org/ > > Posting guidelines: > https://github.com/joyent/node/wiki/Mailing-List-Posting-Guidelines > > You received this message because you are subscribed to the Google > > Groups "nodejs" group. > > To post to this group, send email to [email protected]<javascript:> > > To unsubscribe from this group, send email to > > [email protected] <javascript:> > > For more options, visit this group at > > http://groups.google.com/group/nodejs?hl=en?hl=en > -- Job Board: http://jobs.nodejs.org/ Posting guidelines: https://github.com/joyent/node/wiki/Mailing-List-Posting-Guidelines You received this message because you are subscribed to the Google Groups "nodejs" group. To post to this group, send email to [email protected] To unsubscribe from this group, send email to [email protected] For more options, visit this group at http://groups.google.com/group/nodejs?hl=en?hl=en
