Proposal: change deprecation policy

[toddself]

The current node deprecation policy is very difficult for certain sets of node users to find out about breaking changes between LTS-enabled node versions.

With node's tick/tock even/odd release cycle where odd-numbered releases will never enter an LTS mode, it is very possible to miss the deprecation of a much-relied upon feature because there's no business reason for me to test my code against a version of node that I will never release my services on top of.

As with #12976, many people who rely on not having to provide callbacks to asynchronous functions would have been caught blind by migrating from 6 to 8, skipping over the deprecation warning entirely and going from "this works" to "this kills my node process entirely"

Given the speed at which the node community releases major versions (4 was released like barely over a year ago and we're almost to 8!), it would be extremely beneficial to extend the deprecation period to always include an LTS-enabled version of the project. This way us "leapfroggers" don't have to deal with vastly unexpected issues with our code bases and can provide feedback on breaking changes during an appropriate window without the added baggage of trying to get a rollback performed.

[ChALkeR]

it is very possible to miss the deprecation of a much-relied upon feature because there's no business reason for me to test my code against a version of node that I will never release my services on top of.

I (personally) believe that this is a self-contradictory statement and suggest everyone to note that.

---

So, do I get it correct that the proposal is to slow down the deprecation process twice and account only LTS releases? There would be significant drawbacks if that would be enforced…

That said, I'm not saying that I am strictly against this proposal now (more like a -0 currently) — I haven't collected and estimate the data on this yet.

/cc @nodejs/ctc, btw, as this proposes a serious process change.

[toddself]

I (personally) believe that this is a self-contradictory statement and suggest everyone to note that.

fs.writeFile's callback omission was deprecated in 7. 7 will never enter LTS. I have not run it anywhere (even in CI), nor do I have plans to.

I will switch to Node 8 when it enters LTS. Because I will never run node 7 anywhere I would miss this deprecation entirely. From my perspective it would be working in node 6, but broken in node 8 (and broken in a way that would cause my services to stop running due to uncaught exceptions being thrown).

Deprecations serve as a way to inform your user base a breaking change is coming. If we miss the deprecation because it's being done on a version that we aren't using, what purpose does the deprecation serve? We are unable to properly act upon it since we didn't ever actually get the deprecation.

I would love for deprecations on functionality on at least modules marked stable to go through at least ONE LTS version before actually being deprecated.

eg: fs.writeFile is marked as deprecated in 7 AND 8, and then removed in 9. Or it's deprecated in 8 and removed in 9.

[jasnell]

hmmm.. a quick clarifying question: would the intention of this be that some bit of Deprecated code could not be EOL'd until after the LTS cycle completes?

For instance, let's say we deprecate some function today in master. That deprecation will occur 8.0.0. Let's say we get another semver-major PR in june that EOL's that code and removes it entirely. That EOL would not go into a release until 9.0.0 next October.

With the proposed change: Is that OK since the deprecation would include an LTS release branch (that is, the API is guaranteed to exist through the lifetime of 8.x but disappear from 9.0.0 onwards). Or... can the code not be EOL'd at all until 8.x LTS expires? (Which means not landing the EOL until Node 14!!)

[mscdex]

I'm curious as to why you would explicitly not test non-LTS releases (especially in CI)?

[toddself]

I'm curious as to why you would explicitly not test non-LTS releases (especially in CI)?

A lot of reasons? I don't have the time to setup CI to run on multiple node versions, our CI success gates whether or not something can be merged, so we'd then have to fix things that aren't broken, or get fixes from upstream providers (or upstream of upstream, etc), the list sort of goes on from there, but I think those two issues should suffice enough to satisfy that curiousity.

For instance, let's say we deprecate some function today in master. That deprecation will occur 8.0.0. Let's say we get another semver-major PR in june that EOL's that code and removes it entirely. That EOL would not go into a release until 9.0.0 next October.

That seems to be the current policy right? Node gets semver-major every 6 months. 9 comes out in Oct 2017. If 8 wasn't late due to turbofan (again a great reason to delay it!), that means something you want to deprecate today would not be able to be removed until Node 11 in Oct 2018 (since it would be deprecated in 9 and 10). This gives the ecosystem adequate time to catch up to larger scale changes.

Again though, this should be only used when making a semver major change to an API marked as stable. You wanna deprecate something with N-API, follow the current deprecation rules since that module is marked as unstable.

[Trott]

I thought runtime deprecation warnings are supposed to be in place for two major releases specifically to guarantee that they end up in an LTS release before anything gets removed. @jasnell Isn't that the intention of the deprecation policy you drafted at https://github.com/nodejs/node/blob/98609fc1c4635f02f8f6ef9dd079207a1204b9a1/COLLABORATOR_GUIDE.md#deprecations?

@toddself Am I misunderstanding you? Or is that basically what you're asking for?

If I'm right and that's part of our policy, then the problem may be that we haven't been following our policy. If that's the case, there are a few possible causes. One is that the policy seems a bit confusingly worded. End-of-Life Deprecation is basically the same thing as Runtime Deprecation. So something is in Runtime Deprecation for a major release. Then it's in End-of-Life Deprecation for a major release, which is the same thing--just a name change. Then, at some point in the future, it may get removed. At least that's how I'm reading it. Am I wrong? If I'm not wrong (and maybe even if I am), then a simplification/clarification of the existing policy text might be useful.

[jasnell]

The End-of-Life phase is currently intentionally non-committal as to when the code can actually be removed (or the behavior changed). Within the current policy, the idea is that End-of-Life code can be changed or removed at any time following the move to End-of-Life. Moving code to End-of-Life is a semver-major action so it is only supposed to happen with a major release.

(In other words, code that is in End-of-Life status has essential the same semver status as code in Experimental status... breaking changes can occur at any time within a major.. so long as the move to End-of-Life itself is consider a semver-major change)

[Trott]

(In other words, code that is in End-of-Life status has essential the same semver status as code in Experimental status... breaking changes can occur at any time within a major.. so long as the move to End-of-Life itself is consider a semver-major change)

@jasnell With the understanding that you are free to change your mind after more thinking about it, what's your immediate reaction to "We ought to generally require runtime deprecation for two major releases?" Yes, I like it? No, I hate it? Not sure, gotta think about it?

(The "generally" in there is to acknowledge that there needs to be an exception process of some kind for things like what happened with the legacy debug API.)

[mscdex]

"We ought to generally require runtime deprecation for two major releases?"

That wouldn't necessarily need to be the case if the main focus is on LTS. For example, if a runtime deprecation first happens on v8.x, then why would we necessarily have to extend that through v9.x as well?

[jasnell]

@Trott ... i think there are far too many variables to consider to establish two majors as a minimum. For instance, we may be deprecating some bit of code because some mechanism in V8 is expected to disappear entirely soon after cutting the next major. Or, we may be deprecating because of a security or usability issue. Or we may just be deprecating because we just have a much better way of doing things in a different way. Pushing the runtime deprecation out to a minimum of two majors would not make any of these any easier for the ecosystem to cope with.

What I would like to see is more emphasis on communicating upcoming deprecation policy transitions. Obviously communicating more effectively is not useful if folks aren't listening or paying attention, but there really is only so much that we can do in that regard.

The short version is: I'm -0 on extending out the runtime deprecation cycle because I don't believe it would actually solve the issue.

[mscdex]

I agree. Personally I still don't understand the argument that adding another node version in CI is troublesome, especially if it allows you to catch runtime deprecations early (in case the documentation deprecations were not read), which would solve the original issue. If the issue is there is a bug in a non-LTS node version, then an issue/PR should be created so the problem can be fixed, just like if a bug were to happen in an LTS branch (especially because there is a good chance the bug may be present in the LTS branch as well).

[fl0w]

Wouldn't it be easier to backport deprecations to LTS as semver-patches instead of extending the lifecycle of deprecated features (if running unstable on CI isn't an acceptable practice)?

[jasnell]

runtime deprecations cannot be semver-patch because they have side effects that can break running code (stderr output and new throws when --throw-deprecation is used).

[toddself]

Personally I still don't understand the argument that adding another node version in CI is troublesome

I'm not sure why you don't understand "I don't have the time" to maintain CI for a version we are not going to use. It must be very nice to have all the engineering resources you need at hand to accomplish your goals. If waiting through one LTS release before removing something that has been deprecated in a stable module (which given the current release velocity is a MAXIMUM of one year, but likely to average out to be less than that), great, we can close this issue.