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]> 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]> > 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]> 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] >>> 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 >> >> -- >> 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 > > -- > 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 -- 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
