Deprecation
308 views
Skip to first unread message
Isaac Schlueter
Jun 28, 2012, 9:01:46 PM6/28/12
to nodejs
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.
- 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.
Joshua Holbrook
Jun 28, 2012, 9:11:58 PM6/28/12
to nod...@googlegroups.com
Well said.
--Josh
> --
> 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 nod...@googlegroups.com
> To unsubscribe from this group, send email to
> nodejs+un...@googlegroups.com
> For more options, visit this group at
> http://groups.google.com/group/nodejs?hl=en?hl=en
--
Joshua Holbrook
Engineer
Nodejitsu Inc.
jo...@nodejitsu.com
--Josh
> 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 nod...@googlegroups.com
> To unsubscribe from this group, send email to
> nodejs+un...@googlegroups.com
> For more options, visit this group at
> http://groups.google.com/group/nodejs?hl=en?hl=en
--
Joshua Holbrook
Engineer
Nodejitsu Inc.
jo...@nodejitsu.com
Matt
Jun 28, 2012, 11:08:49 PM6/28/12
to nod...@googlegroups.com
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 ;-)
Isaac Schlueter
Jun 29, 2012, 12:48:09 PM6/29/12
to nod...@googlegroups.com
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 :)
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 :)
john.tiger
Jun 29, 2012, 1:51:08 PM6/29/12
to nod...@googlegroups.com
Thanks Isaac for a good approach (sys vs util). We're one of those not
so big enterprise firms that this helps (even if our stuff is used by
some big firms - they don't care if it's not making an immediate
difference).
We're not against making code changes but haven't seen the benefit yet
of moving from sys to util. Since there are plenty of sharp minds
working on the core team, I assume there is a good reason for the move
but we don't yet know what it is.
so big enterprise firms that this helps (even if our stuff is used by
some big firms - they don't care if it's not making an immediate
difference).
We're not against making code changes but haven't seen the benefit yet
of moving from sys to util. Since there are plenty of sharp minds
working on the core team, I assume there is a good reason for the move
but we don't yet know what it is.
Arunoda Susiripala
Jun 29, 2012, 2:12:16 PM6/29/12
to nod...@googlegroups.com
+100
I was looking for this kind of thought from Node Core. Wow, its not about Sys vs Util,
But about a good community bond.
--
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 nod...@googlegroups.com
To unsubscribe from this group, send email to
Felix Böhm
Jun 30, 2012, 7:05:34 AM6/30/12
to nod...@googlegroups.com
There is so much wrong with this approach: Most importantly, you now have to support everything you supported in 0.4. But as the zero at the beginning of the node version tells, it's not a final product. It's okay to break features. Companies interested in the advantages of the new version need to accept the disadvantages. That's the way jQuery does it. And it's working.
(As a side-note: Of course, as soon as backwards-compat isn't the main goal anymore, every serious security hole needs to be fixed for every version. But as those won't show up on a daily basis, it's not a big issue.)
Another idea: Remove the entire module, so that it won't be found anymore. If sys is still needed, go to your home directory and run
mkdir -p node_modules/sys;echo "module.exports=require('util')">node_modules/sys/index.js
Someone could even add a sys module to npm, containing that single line. Congrats, fixing this issue is now adding a single entry to your package.json.
Reply all
Reply to author
Forward
0 new messages