Upgrades the migration guide

packages/gatsby/content/advanced/contributing.md

@@ -12,21 +12,21 @@ We have some rules regarding our issues. Please check [the following page](/adva
 
 ## How can you help?
 
-  - Review our documentation! We often aren't native english speakers, and our grammar might be a bit off. Any help we can get that makes our documentation more digest is appreciated!
+- Review our documentation! We often aren't native english speakers, and our grammar might be a bit off. Any help we can get that makes our documentation more digest is appreciated!
 
-  - Talk about Yarn in your local meetups! Even our users aren't always aware of some of our features. Learn, then share your knowledge to your own circles!
+- Talk about Yarn in your local meetups! Even our users aren't always aware of some of our features. Learn, then share your knowledge to your own circles!
 
-  - Help with our infra! There are always small improvements to do: run tests faster, uniformize the test names, improve the way our version numbers are setup, ...
+- Help with our infra! There are always small improvements to do: run tests faster, uniformize the test names, improve the way our version numbers are setup, ...
 
-  - Write code! We have so many features we want to implement, and so little time to actually do it... Any help you can afford will be appreciated, and you will have the satisfaction to know that your work helped literally millions of developers!
+- Write code! We have so many features we want to implement, and so little time to actually do it... Any help you can afford will be appreciated, and you will have the satisfaction to know that your work helped literally millions of developers!
 
 ## Finding work to do
 
 It might be difficult to know where to start on a fresh codebase. To help a bit with this, we try to mark various issues with tags meant to highlight issues that we think don't require as much context as others:
 
-  - [Good First Issue](https://github.com/yarnpkg/berry/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) are typically self-contained features of a limited scope that are a good way to get some insight as to how Yarn works under the hood.
+- [Good First Issue](https://github.com/yarnpkg/berry/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) are typically self-contained features of a limited scope that are a good way to get some insight as to how Yarn works under the hood.
 
-  - [Help Wanted](https://github.com/yarnpkg/berry/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) are issues that don't require a lot of context but also have less impact than the ones who do, so no core maintainer has the bandwidth to work on them.
+- [Help Wanted](https://github.com/yarnpkg/berry/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) are issues that don't require a lot of context but also have less impact than the ones who do, so no core maintainer has the bandwidth to work on them.
 
 Finally, feel free to pop on our [Discord channel](https://discordapp.com/invite/yarnpkg) to ask for help and guidance. We're always happy to see new blood, and will help you our best to make your first open-source contribution a success!
 
@@ -36,53 +36,53 @@ The standard bundle uses a predefined set of plugins defined in [`packages/yarnp
 
 For development purposes, you can build your plugin as part of your own local bundle by using the `--plugin` option in the command line:
 
-```
-$> yarn build:cli --plugin @yarnpkg/plugin-typescript
+```bash
+yarn build:cli --plugin @yarnpkg/plugin-typescript
 ```
 
 ## Testing your code
 
 We currently have two testsuites, built for different purposes. The first one are unit tests and can be triggered by running the following command from anywhere within the repository:
 
-```
-$> yarn test:unit
+```bash
+yarn test:unit
 ```
 
 While various subcomponents that have a strict JS interface contract are tested via unit tests (for example the portable shell library, or the various util libraries we ship), Yarn as a whole relies on integration tests. Being much closer from what our users experience, they give us a higher confidence when refactoring the application that everything will work according to plan. Those tests can be triggered by running the following command (again, from anywhere within the repository):
 
-```
-$> yarn build:cli
-$> yarn test:integration
+```bash
+yarn build:cli
+yarn test:integration
 ```
 
 Note that because we want to avoid adding the `@babel/register` overhead to each Yarn call the CLI will need to be prebuilt in order for the integration tests to run - that's what the `yarn build:cli` command is for. This unfortunately means that you will need to rebuild the CLI after each modification if you want the integration tests to pick up your changes.
 
 Both unit tests and integration tests use Jest, which means that you can filter the tests you want to run by using the `-t` flag (or simply the file path):
 
-```
-$> yarn test:unit berry-shell
-$> yarn test:integration -t 'it should correctly install a single dependency that contains no sub-dependencies'
+```bash
+yarn test:unit berry-shell
+yarn test:integration -t 'it should correctly install a single dependency that contains no sub-dependencies'
 ```
 
 Should you need to write a test (and you certainly will if you add a feature or fix a bug 😉), they are located in the following directories:
 
-  - **Unit tests:** [`packages/*/tests`](https://github.com/search?utf8=%E2%9C%93&q=repo%3Ayarnpkg%2Fberry+filename%3Atest.ts+language%3ATypeScript+language%3ATypeScript&type=Code&ref=advsearch&l=TypeScript&l=TypeScript)
-  - **Integration tests:** [`packages/acceptance-tests/pkg-test-specs/sources`](https://github.com/yarnpkg/berry/tree/master/packages/acceptance-tests/pkg-tests-specs/sources)
+- **Unit tests:** [`packages/*/tests`](https://github.com/search?utf8=%E2%9C%93&q=repo%3Ayarnpkg%2Fberry+filename%3Atest.ts+language%3ATypeScript+language%3ATypeScript&type=Code&ref=advsearch&l=TypeScript&l=TypeScript)
+- **Integration tests:** [`packages/acceptance-tests/pkg-test-specs/sources`](https://github.com/yarnpkg/berry/tree/master/packages/acceptance-tests/pkg-tests-specs/sources)
 
 The `makeTemporaryEnv` utility generates a very basic temporary environment just for the context of your test. The first parameter will be used to generate a `package.json` file, the second to generate a `.yarnrc.yml` file, and the third is the callback that will be run once the temporary environment has been created.
 
 ## Formatting your code
 
 Before submitting your code for review, please make sure your code is properly formatted by using the following command from anywhere within the repository:
 
-```
-$> yarn test:lint
+```bash
+yarn test:lint
 ```
 
 We use ESLint to check this, so using the `--fix` flag will cause ESLint to attempt to automatically correct most errors that might be left in your code:
 
-```
-$> yarn test:lint --fix
+```bash
+yarn test:lint --fix
 ```
 
 ## Preparing your PR to be released
@@ -91,7 +91,7 @@ In order to track which packages need to be released we use the workflow describ
 
 If you expect a package to have to be released again but Yarn doesn't offer you this choice, first check whether the name of your local branch is `master`. If that's the case, Yarn might not be able to detect your changes (since it will do it against `master`, which is yourself). Run the following commands:
 
-```
+```bash
 git checkout -b my-feature
 git checkout -
 git reset --hard upstream/master
@@ -105,8 +105,8 @@ If it fails and you have no idea why, feel free to ping a maintainer and we'll d
 
 Our website is stored within the [`packages/gatsby`](https://github.com/yarnpkg/berry/tree/master/packages/gatsby) directory. *Do not manually edit the html files in the `docs` folder!* Instead, just make your changes in the Gatsby directory (for example you'd edit this very page [here](https://github.com/yarnpkg/berry/blob/master/packages/gatsby/content/advanced/plugin-tutorial.md)), then run the following command to spawn a local server and see your changes:
 
-```
-$> yarn develop
+```bash
+yarn develop
 ```
 
 Once you're happy with what the documentation looks like, just commit your local changes and open a PR. Netlify will pick up your changes and spawn a fresh preview for everyone to see:

packages/gatsby/content/advanced/lifecycle-scripts.md

@@ -26,6 +26,6 @@ Unfortunately postinstall scripts break this model because they signal Yarn that
 
 Depending on your use case, here's how you can avoid postinstall scripts:
 
- - Native packages can be built to [WebAssembly](https://webassembly.org), which is already supported in Node 12 and beyond. On top of being portable and fast, WebAssembly packages also have the benefit to make your libraries available not only to Node but also to your browser users. And since their compilation is made upfront, your users won't be impacted by slow compilation time problems.
+- Native packages can be built to [WebAssembly](https://webassembly.org), which is already supported in Node 12 and beyond. On top of being portable and fast, WebAssembly packages also have the benefit to make your libraries available not only to Node but also to your browser users. And since their compilation is made upfront, your users won't be impacted by slow compilation time problems.
 
 - Project sustainability is a big topic, but the gist is that we don't think postinstall scripts are a viable solution. We however are committed to provide a specific field in the package.json that would signal to the package managers that a project would like to communicate its existence with the user in an integrated and respectful way.

packages/gatsby/content/advanced/migration.md

@@ -8,19 +8,31 @@ Yarn v2 is a very different software from the v1. While one of our aim is to mak
 
 ## General Advices
 
+### Upgrade to Node 10 or 12
+
+Yarn doesn't support Node 8 anymore, as it's reached its end of life in December and won't receive any further update.
+
 ### Make sure you use `[email protected]+`
 
 Older releases don't support Plug'n'Play at all. Since the `resolve` package is used by pretty much everything nowadays, making sure that you use a modern release can go a long way to solve the most obnoxious bugs you may have.
 
 **Fix:** Open your lockfile, look for all the `resolve` entries that could match 1.9+ (for example `^1.0.0`), and remove them. Then run `yarn install` again. If you run `yarn why resolve`, you'll also get a good idea of which package is depending on outdated version of `resolve` - maybe you can upgrade them too?
 
+### Enable the PnP plugin when using Webpack 4
+
+Webpack 5 will support PnP natively, but if you use Webpack 4 you'll need to add the [`pnp-webpack-plugin`](https://github.com/arcanis/pnp-webpack-plugin) plugin yourself.
+
 ### Call your scripts through `yarn node` rather than `node`
 
 We now need to inject some variables into the environment for Node to be able to locate your dependencies. In order to make this possible, we ask you to use `yarn node` which transparently does the heavy lifting.
 
 **Note:** this section only applies to the _shell CLI_. The commands defined in your `scripts` are unaffected, as we make sure that `node` always points to the right location.
 
-### Updates your configuration to the new settings
+### Setup your IDE accordingly
+
+We've written a [guide](https://next.yarnpkg.com/advanced/editor-sdks) entirely designed to explain you how to use Yarn with your IDE. Make sure to take a look at it, and maybe contribute to it if some instructions are unclear or missing!
+
+### Update your configuration to the new settings
 
 Yarn 2 uses a different style of configuration files than Yarn 1. While mostly invisible for the lockfile (because we import them on the fly), it might cause some issues for your rc files.
 
@@ -36,7 +48,7 @@ Yarn 2 uses a different style of configuration files than Yarn 1. While mostly i
 
   - The `yarn-offline-mirror` has been removed, since the offline mirror has been merged with the cache as part of the [Zero-Install effort](/features/zero-installs). Just commit the Yarn cache and you're ready to go.
 
-### Don't use the `.npmrc` files
+### Don't use `.npmrc` files
 
 On top of their naming, the way we load the Yarnrc files has also been changed and simplified. In particular:
 
@@ -46,7 +58,7 @@ On top of their naming, the way we load the Yarnrc files has also been changed a
 
 - All environment variables prefixed with `YARN_` are automatically used to override the matching configuration settings. So for example, adding `YARN_NPM_REGISTRY_SERVER` into your environment will change the value of [`npmRegistryServer`](/configuration/yarnrc#npmRegistryServer).
 
-### Take a look to the integration tests
+### Take a look to our end-to-end tests
 
 We now run daily [end-to-end tests](https://github.com/yarnpkg/berry#current-status) against various popular JavaScript tools in order to make sure that we never regress - or to be notified when those tools do.
 
@@ -71,19 +83,19 @@ So how to replace them? There are different ways:
 
 Despite our best efforts some tools don't work at all under Plug'n'Play environments, and we don't have the resources to update them ourselves. There are only two notorious ones on our list: Flow, and React Native.
 
-In such a radical case, you can install the [`node-modules` plugin]() by running `yarn plugin import node-modules`. Once done, enable the linker in your local `.yarnrc.yml` file before running a fresh `yarn install`:
+In such a radical case, you can enable the [`node-modules` plugin](https://github.com/yarnpkg/berry/tree/master/packages/plugin-node-modules) by adding the following into your local `.yarnrc.yml` file before running a fresh `yarn install`:
 
 ```yaml
 nodeLinker: node-modules
 ```
 
-This will cause Yarn to install the project just like Yarn 1 used to, by copying the packages into various `node_modules` folders. This install strategy is typically quite a bit slower and less stable than the modern one (read [Plug'n'Play](/features/pnp) for more details), but at the very least this will allow you to upgrade to our new CLI until you're ready to drop the `node_modules` linker.
+This will cause Yarn to install the project just like Yarn 1 used to, by copying the packages into various `node_modules` folders. Remember that this plugin is currently very experimental and we expect it to improve over time.
 
 ## Troubleshooting
 
 ### `Cannot find module [...]`
 
-Interestingly, this error **doesn't** come from Yarn. In fact, seeing this message shouldn't be possible when working with Yarn 2 projects and typically highlights that something is wrong in your setup.
+Interestingly, this error **doesn't** come from Yarn. In fact, seeing this message should be extremely rare when working with Yarn 2 projects and typically highlights that something is wrong in your setup.
 
 This error appears when Node is executed without the proper environment variables. In such a case, the underlying application won't be able to access the dependencies and Node will throw this message. To fix that, make sure that the script is called through `yarn node [...]` (instead of `node [...]`) if you run it from the command line.
 

packages/gatsby/content/getting-started/install.md

@@ -4,14 +4,18 @@ path: /getting-started/install
 title: "2 - Installation"
 ---
 
+> **Migrating from Yarn 1**
+>
+> We've been compiling helpful advices when porting over from Yarn 1 on the following [Migration Guide](/advanced/migration). Give it a look and contribute to it if you see things that aren't covered yet!
+
 ## Global Install
 
 1. Install [Node.js](https://nodejs.org/en/download/)
 
 2. Install Yarn:
 
-```
-npm install -g yarn
+```bash
+npm install -g yarn@berry
 ```
 
 3. Test that Yarn 2 has been properly installed by running the following, which should yield "v2.0.0" or similar:

packages/gatsby/content/getting-started/usage.md

@@ -12,54 +12,55 @@ Now that you have Yarn [installed](/getting-started/install), you can start usin
 
 ### Accessing the list of commands
 
-```
+```bash
 yarn help
 ```
 
 ### Starting a new project
 
-```
+```bash
 yarn init
 ```
 
 ### Installing all the dependencies
 
-```
+```bash
 yarn
 yarn install
 ```
 
 ### Adding a dependency
 
-```
+```bash
 yarn add [package]
 yarn add [package]@[version]
 yarn add [package]@[tag]
 ```
 
 ### Adding a dependency to different categories of dependencies
 
-```
+```bash
 yarn add [package] --dev  # dev dependencies
 yarn add [package] --peer # peer dependencies
 ```
 
 ### Upgrading a dependency
 
-```
+```bash
 yarn up [package]
 yarn up [package]@[version]
 yarn up [package]@[tag]
 ```
 
 ### Removing a dependency
 
-```
+```bash
 yarn remove [package]
 ```
 
 ### Upgrading Yarn itself
 
-```
+```bash
+yarn set version 2.0.0
 yarn set version from sources
 ```