Document 0.10 & 0.12 to LTS changes for migration

[rvagg]

To ease the pain for users switching from 0.10 and 0.12 to LTS we need to provide better documentation, currently we have very little.

There's two main areas:

• Breaking changes: listed as things you must pay attention to in your applications because stuff will break.
• Additions that are not necessarily breaking but are interesting because:
  1. they add interesting & useful features
  2. they change behaviour in a way that's not breaking but may be unexpected (e.g. lower memory usage for TLS)
  3. they present a potential risk for breaking existing usage—the fact is that we can't test every workflow & use-case of Node so we honestly can't say that any change won't be breaking for some user, this is where this list is most helpful to large users who are risk averse; if we give them insight to the areas that have changed they at least know where to look.

C++ API changes are another part of this but obviously. Can be fleshed out with NAN 2 docs if necessary

Dot-points with links to pull requests would be enough to get started. Probably also worth doing this in the LTS wiki.

Some of the existing resources:

• https://github.com/nodejs/LTS/wiki/Breaking-changes-between-v0.12-and-next-LTS-release
• https://github.com/joyent/node/wiki/API-changes-between-v0.10-and-v0.12
• https://github.com/nodejs/node/blob/master/CHANGELOG.md#summary-of-changes-from-nodejs-v01035-to-iojs-v100
• https://github.com/nodejs/node/issues?utf8=%E2%9C%93&q=is%3Aclosed+label%3Asemver-major
  https://github.com/nodejs/node/issues?utf8=%E2%9C%93&q=is%3Aclosed+label%3Asemver-minor
• https://github.com/nodejs/nan#api (there's a lot of stuff if you follow the links, no need to copy/paste it but can link)
• https://v8docs.nodesource.com/ (used heavily by the NAN docs)
• io.js v3 preparation nan#376 (I have a migration guide for NAN 2 in progress, hopefully published soon)

If you start working on any of this, please keep us informed in this thread so we don't end up overlapping work.

[rvagg]

I've done a partial merge of the nodejs/node-v0.x-archive wiki and the nodejs/node wiki (via git) and so far just moved the API/migration guides and also left placeholders on the nodejs/node-v0.x-archive wiki pointing to their new location so we don't have duplicates.

There is now a placeholder doc for v0.10 -> v4 @ https://github.com/nodejs/node/wiki/API-changes-between-v0.10-and-v4 and @Fishrock123 has a ton of content he's been preparing for this that he'll drop very shortly.

/cc @evanlucas cause I noticed you were editing that doc, perhaps hold off on major work until @Fishrock123's changes have landed

[evanlucas]

Ah thanks for the heads up. Sorry, saw you had created the page and was trying to help out :]

I'll take a look after he gets the changes in.

[Fishrock123]

I dumped my content into there. This can probably be closed?