node-convergence-archive
node-convergence-archive copied to clipboard
nodejs
docs: Add deprecation policy
-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.
"Until we've determined breakage is below a given threshold, on a per-feature basis" would be my preference.
@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 :)
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.
@rlidwka you can put it wherever you want... the point is to establish a policy.
This still need more discussion. Also, it should probably be PR'd to the io.js repo for now.
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.
@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.
@geek its a good conversation to start having, thanks for kicking it forward.
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.
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.
Imo dev-policy should eventually live in-tree, because then people will actually see it and it seems more official.
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.
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.
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.
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.