docs: Add deprecation policy

[geek]

Closes nodejs/node#1704

[chrisdickinson]

-1 on this. Breaking end-user code at the end of a pre-determined 3-month cycle without any idea of the downstream impact is not acceptable.

[chrisdickinson]

This goes against what we've defined previously in the dev-policy, with regards to "implicit" and "explicit" public APIs, IIRC.

[geek]

@chrisdickinson how long of a period do you need, 5 months, a year?

[chrisdickinson]

"Until we've determined breakage is below a given threshold, on a per-feature basis" would be my preference.

[geek]

@chrisdickinson I think that has a solid spirit and goal to it. You are, however, tying yourself to legacy code and future code that chooses to use the API you want to delete.

Instead, lets have a hard and fast policy and do our best to keep people on board with changes. We can build a much cleaner framework if we are allowed to clean it :)

[rlidwka]

Why are we putting a 5th document into the root of the project that's not used by any of the tools? It's getting a bit crowded there.

[geek]

@rlidwka you can put it wherever you want... the point is to establish a policy.

[jasnell]

This will likely need to come up on the tsc-agenda. /cc @nodejs/tsc

[Fishrock123]

This still need more discussion. Also, it should probably be PR'd to the io.js repo for now.

[sam-github]

If deprecated APIs are never deleted, people come to ignore the deprecation warnings, because they are effectively meaningless, leading to a situation where you can never delete them because nobody stopped using them, and deleting them is high-impact.

But 3 months seems pretty arbitrary to me, too.

Introducing a deprecation in a semver-major release, and then deleting in the next semver-major release might be more predictable. Depending on how predictable semver-major releases are.

[geek]

@sam-github 3 months is entirely arbitrary... I am more trying to get the conversation started and provide a basic set of ideas. I think your suggestion makes more sense, let the major version dictate the deletion.

[sam-github]

@geek its a good conversation to start having, thanks for kicking it forward.

[mikeal]

Why are we putting a 5th document into the root of the project that's not used by any of the tools? It's getting a bit crowded there.

Because every time we add one someone says "why another file in the root?" and then nobody creates a directory and we end up putting it in the root anyway :)

Someone should send a PR moving all but LICENSE and CONTRIBUTING to a directory.

[jasnell]

Or move those to a separate repo entirely. We do have dev-policy available for use. The deprecation policy document really ought to live there.

[Fishrock123]

Imo dev-policy should eventually live in-tree, because then people will actually see it and it seems more official.

[mikeal]

Ya, also the dev policy is specific to nodejs/io.js and nodejs/node. Once we are down to just nodejs/node it would be a little strange for the policy to live in a separate repo. We should keep the repo around indefinitely though just to reference all the conversations we had there.

[chrisdickinson]

Ideally these docs would live in doc/internal – I've been collecting documents in that direction, but I have yet to make the requisite internal doc sprint.

[Fishrock123]

doc/internal may not be visible enough though.

[chrisdickinson]

There are ways we can mitigate that – huge-big links on the README to appropriate docs, making sure there are decent "landing page" indexes for internal docs, hosting on the main site.

[mikeal]

Another thing I just thought about: we're doing RC builds for major releases now and have pulled breaking changes from those once we realized their impact was larger than originally estimated. We may want to standardize a timeframe that we hold majors in RC when there are deprecations so we can continue to understand their impact.