Matt,
Good idea.
As with any policy with Node, the rule is important, but the point of
the rule is even more important. If this ever turns out to be no
good, we'll just change it again :)
On Thu, Jun 28, 2012 at 8:08 PM, Matt <hel...@gmail.com> wrote:
> 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
--
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
