Deprecation Policy

[jasnell]

The dev-policy currently does not include anything about the deprecation process. If we're going to cover reversions, we ought to cover deprecations also.

[mikeal]

This also came up in the last TC meeting. My recollection of what we said was:

• Mark API as deprecated in the docs. Wait a full major cycle before taking any further action.
• Consider printing a dep warning. Wait a full major cycle before taking any further action.
• Consider removal.

In some (possibly most) cases we won't make it past the first step and it's possible we never make it to the third.

[chrisdickinson]

@domenic also suggested having a "pending-deprecation" state that coincides with the "mark API deprecated" step for folks to proactively seek out deprecations ahead of time, which I'm in favor of.

[Fishrock123]

Something that isn't too complex.

2-3 steps might be ok as @mikeal said.

• Deprecate in docs if it was documented (+Major cycle)
• util.deprecate (skip to here if was undocumented) (+Major cycle)
• consider removing

[mhdawson]

Just wondering why the gap between deprecating in the docs and the util.deprecate. Along the same lines as Chris's comment above I'd like it to be easy to pro-actively identify deprecated methods automatically as soon as possible.

Once its in the docs I can see it helping people to stop using it but have we seen people quickly remove it from their existing code once only the docs are updated ?

[thefourtheye]

What is the official word on this? I feel that the doc and deprecation notice can land together in a major and the removal can happen in the next major bump.