doc: document deprecation of util._extend

[benjamingr]

doc: document deprecation of util._extend

See the discussion here #4593 for more
details as well as the 2016-01-20 minutes.

[benjamingr]

Something went very wrong with git in #4902 , so I created a new PR.

[thefourtheye]

I suggested a change in #4907. If it gets through, we can make the Object.assign() a link.

[benjamingr]

Great, now that it landed I'll edit it into it.

[jasnell]

@nodejs/ctc ... defensively marking as semver-major since it's a deprecation. If anyone feels that too strong, lemme know

[brendanashworth]

I think you need to escape (\_) the underscore for markdown.

[thefourtheye]

I think we conveyed this at the top of the page. https://nodejs.org/api/util.html#util_util

[ljharb]

Is there any benefit in recommending a polyfill so that modules can use Object.assign and retain compatibility with older nodes? Specifically, require('object.assign/polyfill')() will return the best available function (ie, native, unless it's broken or absent).

[benjamingr]

@ljharb in all honesty I think most differences @domenic outlined, while extremely important in evaluating removing _extend are things "average" users would never run into. A single example using ._extend in the wild that would break can go a long way to convince me otherwise though.

[ljharb]

Yes, I'm not trying to strengthen the case to deprecate _extend, i'm saying that if users want to use Object.assign but don't want to drop support for older nodes that don't have it, they could use the object.assign package.

[silverwind]

Not sure I agree with this, naming it "deprecation" seems weird. I think if we're going to do this, I'd rather have it be labeled "discouragement" or similar. Also, as others have pointed out, Object.assign is not 100% compatible. -1 from me.

[vkurchatkin]

-1. We shouldn't add something that was never public just to say that it's deprecated

[benjamingr]

@vkurchatkin @silverwind I was under the impression I'm following the consensus reached at the TSC 2016-01-20 meeting.

[silverwind]

Link to the discussion. I wouldn't object if CTC want's to push this through, just my opinion.

[silverwind]

Also, I'm +1 on documenting it. I'd be happy if you remove the deprecation badge and add a note that it's discouraged.

[vkurchatkin]

@benjamingr well, I disagree nonetheless)

[thefourtheye]

-1. We shouldn't add something that was never public just to say that it's deprecated

@vkurchatkin If we cannot document it, then we cannot deprecate it as per the current deprecation process right?

[jasnell]

LGTM. This is in line with the CTC discussion and decision.

[benjamingr]

I'd like to give @vkurchatkin and @silverwind a chance to express their views and pursue changing the decision first :)

[benjamingr]

Hey, I'm not sure how to move forward with this. @vkurchatkin @silverwind is there another way you'd write this? I don't mind following up with a different PR if you have an idea that will convey that status you can agree with.

[silverwind]

Looking at it again, I don't think it's really that much of a big deal calling it 'deprecation' as I may have made it out to be, so LGTM.

[jasnell]

Landed in d829028