Breaking changes between v0.12.x and next LTS releases cycle

[misterdjules]

@jasnell asked the question a while ago whether a v0.14.x LTS cycle would be needed before moving to using nodejs/node to release LTS releases.

The main reason I believe for this question is there's a significant amount of uncertainty from users of the current stable release of Node.js about what will break when they upgrade to the next LTS releases that will come from the merged repository.

What I had suggested at that time was that we:

1. Document what the breaking changes would be for users switching from v0.12.x to a release from the converged repo.
2. Reach out to the broadest set of representative users as we can to identify critical concerns on such a migration.

And finally we would use the outcome of step 1 and 2 to make a decision whether a v0.14.x is needed. I would expect it's not needed, but we'll be able to provide a smoother transition path by documenting breaking changes better, and fixing some issues ahead of time.

I made some progress on step 1 and put together what I think is a list of breaking changes between v0.12.x and what will be the merged nodejs/node repository.

Before moving to step 2, I would like as many members of @nodejs/lts as possible review that list and comment in this issue.

/cc @nodejs/lts

[rvagg]

I've put some work into that wiki page, fleshing it out a bit and making it more digestible.

One item I think needs removing is url: url.resolve() with URLs with trailing '.' or '..' which I believe landed in 0.10 as well as io.js, ref nodejs/node#278 & nodejs/node-v0.x-archive#9010, I haven't removed it but I put a note since I haven't dug deeply into the details.

Also, I remove the url.parse() breaking issue because we reverted that before it went to a release so the changes are only internal reworking and should not impact users (but of course you never really know).

[misterdjules]

@rvagg Thank you for making the document easier to read 👍 The url.resolve changes have been reverted in v0.10 and v0.12, so I would still keep this entry in that document. I will remove your note now, but please feel free to let me know if you think of a better way to handle this.

[mhdawson]

Julien the document looks good. One thought I had was whether we should include what we believe the risk is that each change will break existing code and possibly include an example of cases that will be broken. Not important so much now as we build the list but when we publish it so that it makes it easy for people to understand what the impact might be to them

[misterdjules]

@mhdawson Excellent suggestion, thank you!