[docs] how to upgrade Gatsby and dependencies for minor/patch releases

[marcysutton]

Summary

We should add a doc on how to upgrade Gatsby after you've created a site. For many developers, the steps to do that are not obvious and there's likely some fear that typing in random commands could break things.

In the Releases & Migration section of the docs, we could list out both the reasons and steps for how to upgrade. Ultimately when paired with prompts in the CLI (cc @KyleAMathews), I suspect users will upgrade more regularly.

A doc on Gatsby upgrades should mention any gotchas related to semver/breaking changes, what to do if an upgrade goes wrong, and all necessary steps to updating relevant dependencies.

[jletey]

@marcysutton I can give this a go!

[jjcav84]

@marcysutton for clarification is this upgrading from version 1 to version 2 or does this include minor versions?

[marcysutton]

@jjcav84 that doc already exists: https://www.gatsbyjs.org/docs/migrating-from-v1-to-v2/

Sorry, I should have clarified! This is for minor/patch upgrades; people tend to install Gatsby and then rarely update it again.

Thanks for taking it on! Let me know if you have any other questions.

[darrell24015]

Need any additional help with this? I've had a couple of times where I've been prompted to update and worried it might break something in the build. Also, is there some documentation that addresses moving the local build from one PC/Laptop to another? I have three different laptops that I do dev work on (depending where I'm working at the moment).

[marcysutton]

is there some documentation that addresses moving the local build from one PC/Laptop to another?

I would recommend using Git for that!

[furai]

I could really use such docs or general guidelines about now. I'm searching the net for some best practices but can't find any. Is there any rough write up about how to upgrade minor/patch versions? Is just doing yarn upgrade on default starter repo good enough?

EDIT: Seems like yarn upgrade upgrades way too much.

[gatsbot[bot]]

Hiya!

This issue has gone quiet. Spooky quiet. 👻

We get a lot of issues, so we currently close issues after 30 days of inactivity. It’s been at least 20 days since the last update here.

If we missed this issue or if you want to keep it open, please reply here. You can also add the label "not stale" to keep this issue open!

As a friendly reminder: the best way to see this issue, or any other, fixed is to open a Pull Request. Check out gatsby.dev/contributefor more information about opening PRs, triaging issues, and contributing!

Thanks for being a part of the Gatsby community! 💪💜

[wardpeet]

When using yarn I use yarn add gatsby to get the latest. Npm is probably the same npm install gatsby I'm not sure for npm

[m-allanson]

yarn also has yarn upgrade-interactive which lets you pick and choose which packages to update:

[furai]

Another thing that might be worth looking into is fixing inconsistency across documentation with usage of NPM and YARN and actually sticking to one or covering both in each document. I've run into few instances where one tutorial/manual was mentioning usage of one and next one the other.

[wardpeet]

We could also introduce a gatsby upgrade method which upgrades gatsby to the latest version. Gatsby upgrade might become beneficial if we do a major upgrade. We could run codemods to get you upgraded.

Another thing that might be worth looking into is fixing inconsistency across documentation with usage of NPM and YARN and actually sticking to one or covering both in each document. I've run into few instances where one tutorial/manual was mentioning usage of one and next one the other.

Oh that's a great point. Could you point us to some links? We try to advocate NPM as it comes natively with nodejs. The only documentation I'm aware of themes where we use yarn workspaces as NPM doesn't have a baked-in solution for this.

[furai]

I would actually advocate for yarn usage everywhere. I've run into many issues with NPM during setting up many deployments for different technologies/frameworks. While yarn usually worked as expected.

Searching docs for "yarn add" with grep -rn ./docs/ -e "yarn add" shows a few different .MD files where package was added with yarn.

Probably those are mostly pages for plug-ins, not sure though, so the tutorial seems fine. But when you follow the tutorial closely, you're lead to other pages which use yarn. That's why I've noticed inconsistency.

To be honest the best would be to include both instructions for yarn and for npm so people can make up their minds what they want to use.

Right now it's all a bit confusing because of that discrepancy.

Maybe it's also because of the default starter theme?

[darrell24015]

Another thing that might be worth looking into is fixing inconsistency across documentation with usage of NPM and YARN and actually sticking to one or covering both in each document.

Wait - what is YARN? Every course on node.js I've ever taken only talks about NPM. Sorry, that's slightly off-topic. We've identified at least three related items that could use more documentation.

[wardpeet]

@furai we use yarn in those files as npm doesn't support "workspaces" out of the box and we thought it's easier to specify yarn than telling people to setup lernajs.

We might want to add a disclaimer at the top and maybe write a doc about how to set up workspaces with NPM & lernajs.

@darrell24015 It's an NPM alternative. It's 90% compatible with NPM and adds some extra caching/features to NPM. Checkout https://yarnpkg.com/lang/en/.