It's hard to get a correct policy on deprecation, especially when something
becomes popular like Node. I think Isaacs should also add "we reserve the
right to change this policy at any time in the future" to this ;-)
On Thu, Jun 28, 2012 at 9:11 PM, Joshua Holbrook <josh.holbr...@gmail.com>wrote:
> Well said.
>
> --Josh
>
> On Thu, Jun 28, 2012 at 6:01 PM, Isaac Schlueter <i...@izs.me> wrote:
> > tl;dr
> >
> > - In 0.8.1, require("sys") is not going to throw.
> > - The "warn/throw/remove" policy is being updated.
> >
> >
> > ## Backstory
> >
> > Historically, we've been very courageous in node about seeking out the
> > best APIs, even if that means breaking existing programs. Some of you
> > may remember when a "release" was "Ryan pushed something to github",
> > and the entire shape of the API was unrecognizable from one day to the
> > next.
> >
> > As node grew up a little, that changed to "Print a deprecation warning
> > for a stable branch, and then throw in the next, and then gone in the
> > one after that." That's served us pretty well. A lot of features
> > were brand new in 0.4, and we didn't get them all right. The
> > transition to 0.6 was rocky, but the freedom to change things was
> > important, even given the pain it introduced sometimes for users.
> >
> > Almost 2 years ago, we decided to rename the "sys" module to "util",
> > and to fold in the "utils" module. (There was a lot of "generic bag of
> > stuff" code floating around node's internals at that time.) But, even
> > then, there were a lot of people using sys, and it was deemed too
> > agressive to print a warning when it was used.
> >
> > In 0.6, "sys" started printing deprecation warnings. Following the
> > established protocol, in 0.7, we made it throw, with the idea that
> > we'd remove it in 0.9, as is Our Way.
> >
> > As people are moving to 0.8, the most common objection is that
> > require("sys") throws. That's a bit absurd. Following a policy
> > *can't* be more important than breaking peoples' programs.
> > https://github.com/joyent/node/issues/3577
> >
> > Node is growing up. It's used by established companies with
> > reputations and customers and employees that have real work to do.
> > This is a necessary step in our quest for total domination of all the
> > world's programming. Yes, it's an easy change to make. It's also a
> > stupid one to HAVE to make.
> >
> >
> > ## New Policy
> >
> > 1. Every module in the docs has a stability index.
> > http://nodejs.org/api/documentation.html#documentation_stability_index
> > - "experimental" It will probably be changed. Please use and
> > provide feedback, so we change it right.
> > - "deprecated" We reserve the right to remove it if it's in the way,
> > but make no promises that it will be removed, ever.
> > - "unstable" We reserve the right to make changes, but will consider
> > it high-cost
> > - "stable" We will do everything in our power to make this API
> > continue to work for the foreseeable future.
> > - "api frozen" The API will not be changed, even to make additions.
> > - "frozen" No changes to the code, unless a serious bug is found.
> > Code and API are considered "done" and unchanging.
> >
> > 2. Breaking changes, even to deprecated or unstable APIs, are
> > considered costly, and need to pay rent. Higher-stability APIs are
> > more costly to change, but ALL api changes are considered costs. If
> > they don't buy us anything, we don't need to do them.
> >
> >
> > ## Objections
> >
> > No one seems to actually object to sys/util itself, but there are
> > three points that were raised about Node's policies that I'd like to
> > address:
> >
> > 1. So you're saying node will never change ever again and all APIs
> > will be consistent forever? So now Node is PHP/Windows/etc?
> >
> > Of course not. However, from this point forward, we're going to make
> > our best effort to continue to support old programs, even if it means
> > re-implementing them in terms of new APIs. If this actually is not
> > possible, or causes undue harm or maintenance overhead, then we'll
> > reserve the right to warn/throw/remove as we've done.
> >
> > We also reserve the right to change semantics in some cases. There
> > was no cleaner way to fix the child process exit/close stuff but to
> > just bite the bullet and change it. That sucked for a lot of people.
> > It breaks my heart, but we're not going to reverse on that.
> >
> > Most people are pretty understanding if something is actually better.
> > But how is spelling it "util" rather than spelling it "sys" really
> > THAT much better, so much so that you need to throw an error and make
> > my program not work? Seems a bit like an overreaction.
> >
> >
> > 2. So if someone complains enough and is a Big App for Enterprise
> > Business, you're going to just reverse your decision? WTF?
> >
> > Of course not. But we will do our best not to break *anyone's*
> > programs unless we have an extremely compelling reason to do so.
> >
> > Also, we are planning on keeping master in a working state throughout
> > the development of 0.9. If you're moving to v0.8 now, maybe also test
> > on master from time to time. Tell us when something impacts you or
> > stops working.
> >
> > Deprecation reserves the *right* to remove something in the future, it
> > is not a contract that it definitely *will* be removed.
> >
> >
> > 3. What about the cluster "death" vs "exit" event name? What about
> domains?
> >
> > Experimental APIs are clearly labelled in the documentation. **They
> > will almost certainly change.** If you would like to help inform that
> > change, please use them and let us know what parts you like, and what
> > parts are confusing or lacking.
> >
> > We are not committing to always support every API we release, forever.
> > We are committing to considering breaking changes as a high-cost
> > activity. Some high-cost things are worth it. Even some superficial
> > things. The cost of changing experimental APIs is a bit lower, since
> > we've communicated with the stability index that changes are planned.
> >
> > For example, the cluster even name should really be "exit", because
> > that's consistent with the ChildProcess and process event names. The
> > consistency is important there, because it's actually the same sort of
> > "thing" (ie, a javascript object representing a specific operating
> > system process) and it's confusing to have different names for it.
> > Once we get some more feedback about 0.8's cluster, we will probably
> > move it to "Unstable" or even "Stable" in a future release, at which
> > point, you WILL have the assurance that programs using it will not be
> > broken unless absolutely necessary.
> >
> > --
> > 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 nodejs@googlegroups.com
> > To unsubscribe from this group, send email to
> > nodejs+unsubscr...@googlegroups.com
> > For more options, visit this group at
> > http://groups.google.com/group/nodejs?hl=en?hl=en
>
>
>
> --
> Joshua Holbrook
> Engineer
> Nodejitsu Inc.
> j...@nodejitsu.com
>
> --
> 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 nodejs@googlegroups.com
> To unsubscribe from this group, send email to
> nodejs+unsubscr...@googlegroups.com
> 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 nodejs@googlegroups.com
To unsubscribe from this group, send email to
nodejs+unsubscr...@googlegroups.com
For more options, visit this group at
http://groups.google.com/group/nodejs?hl=en?hl=en
