Repository navigation
Let's start to write upgrade guides! #18836
Description
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
Activity
targos commentedon Feb 17, 2018
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 commentedon Feb 17, 2018
I think this is a great idea. I would be happy to help out on this front too!
devsnek commentedon Feb 17, 2018
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 commentedon Feb 18, 2018
By the way, it would be nice to have a codemod based on something like jscodeshift that helps users automatically upgrade their codebase
bnb commentedon Feb 19, 2018
FWIW, there's also the OSS
upgrade-readytool 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 commentedon Feb 20, 2018
Sounds like a good idea to me.
mcollina commentedon Feb 23, 2018
Definitely 👍 . I think we should highlight and promote this for the LTS -> LTS migrations, which have a year worth of changes in them.
Trott commentedon Apr 6, 2018
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 commentedon Apr 7, 2018
@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 commentedon Apr 7, 2018
You have nothing to apologize for. Thanks for trying to make things better for the next person who has to upgrade.
Trott commentedon Oct 26, 2018
Closing due to inactivity, but feel free to re-open if someone is going to make this happen.
skolsuper commentedon May 12, 2021
Did this happen organically somewhere else? The links to the wiki in above comments are broken now too.
Trott commentedon May 12, 2021
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.