Let's start to write upgrade guides!

[targos]

I think there is one thing that Node is missing compared to many other projects when a new major version is released: a clear guide for users who want to migrate their code from an earlier version.

We have lists of breaking changes in the wiki, mostly maintained by @Fishrock123.
Those are valuable, but I would like to propose something different:

• Create a new folder in docs (for example doc/guides/upgrade/)
• When a new major branch is cut, add a new file in this folder for the next major (for example upgrade-to-node-10.md
• Actively update the file during development on the master branch
• Do not just copy/paste commit messages. Write sentences that speak directly to the user reading them
• Illustrate with code and console output examples
• Do not restrict it to semver-major changes. Write about everything that the users might need to know about while upgrading (new core modules/functions, new ES features, doc deprecations, etc.)
• When the release happens, publish the doc to the website and add a link to the download page for some time

/cc @nodejs/collaborators @nodejs/website @nodejs/tsc @nodejs/community-committee

[targos]

Just to clarify the second point: what I mean is that when we branch v10.x, we start working on the upgrade guide to Node 11 (and we finalize the Node 10 one in parallel)

[evanlucas]

I think this is a great idea. I would be happy to help out on this front too!

[devsnek]

i've been meaning to bring this up in a more general sense, about creating wikis for getting started, upgrading, updating, more opinionated tutorials about the "node style" of programming, etc.

as a nice reference: https://www.python.org/about/gettingstarted/

everything linked on that page provides good models for what we should be aiming for (within the reason of node.js being comparable to python)

[joyeecheung]

By the way, it would be nice to have a codemod based on something like jscodeshift that helps users automatically upgrade their codebase

[bnb]

FWIW, there's also the OSS upgrade-ready tool that we built at NodeSource when the 0.10/0.12 -> 4.0 migration happened. Seems to be aligned with the goals of this. Not been updated in a while, but I'd be happy to see what I can do if there's interest ❤️

Huge +1 for this effort in general. Having a codified document will be a massive help for individuals that are getting caught by upgrades.

[mhdawson]

Sounds like a good idea to me.

[mcollina]

Definitely 👍 . I think we should highlight and promote this for the LTS -> LTS migrations, which have a year worth of changes in them.

[Trott]

Related: @fyockm just added this page to the Wiki today: https://github.com//nodejs/node/wiki/Breaking-changes-between-v6-LTS-and-v8-LTS

Seems like it might be a copy/paste of the release notes for the most part. Seems well-intentioned and this might be a fine doc to have in the Wiki (and let other people come along and improve it). Maybe people interested in this Upgrade Guides initiative might find it worthwhile to improve that document.

@nodejs/documentation

[fyockm]

@Trott sorry for the drive-by. Yes, it was just copy/paste from release notes. Seemed like a big hole since we are currently making a big push to migrate from Node 4 to Node 8, and I imagine many others are as well.
Hopefully this helps to get the ball rolling.

[Trott]

sorry for the drive-by

You have nothing to apologize for. Thanks for trying to make things better for the next person who has to upgrade.

[Trott]

Closing due to inactivity, but feel free to re-open if someone is going to make this happen.

[skolsuper]

Did this happen organically somewhere else? The links to the wiki in above comments are broken now too.

[Trott]

Did this happen organically somewhere else? The links to the wiki in above comments are broken now too.

No, I'm afraid it did not happen. Contributions or links to existing materials welcome. I think one thing that has happened, though, is that updating is not the big deal it once was. Backward compatibility is pretty good for the most part.