[v2] Migration guide updates

docs/docs/migrating-from-v1-to-v2.md

@@ -2,44 +2,43 @@
 title: Migrating from v1 to v2
 ---
 
-## Install React, ReactDOM, and each plugins’ peer dependencies manually
-In v1, React and ReactDOM were magically resolved. This “feature” has been removed and you are now required to install them manually.
+> This document is a work in progress. Have you upgraded your site and run into something that's not covered here? Add your changes on GitHub!
 
-```bash
-npm i react react-dom
-```
+## Introduction
 
-or
+This is a reference for upgrading your site from Gatsby v1 to Gatsby v2. While there's a lot covered here, you probably won't need to do everything for your site.
 
-```bash
-yarn add react react-dom
-```
+Let's start with the most important two steps - install React and update your layout components:
 
-Depending on the plugins you use, there may be more dependencies you need to install. For example: if you use typography.js, you now also need to install its dependencies.
+## Install React, ReactDOM, and each plugins’ peer dependencies manually
+
+In v1, the `react` and `react-dom` packages were included as part of the `gatsby` package. They are now `peerDependencies` so you are required to install them into your project.
 
 ```bash
-npm i typography react-typography
+npm i react react-dom
 ```
 
-or
+Some plugins had dependencies that were also made peerDependencies. For example, if you use gatsby-plugin-typography, you now need to install:
 
 ```bash
-yarn add typography react-typography
+npm i typography react-typography
 ```
 
-Search for the plugins that you use in [Gatsby’s plugins page](/plugins) and check their installation instructions.
+Search for the plugins that you use in the [plugin library](/plugins) and check their installation instructions for additional packages that now need installed.
 
 ## Layout component
+
 The special layout component (`src/layouts/index.js`) that Gatsby v1 used to wrap every page has been removed. If the layout of your site appears to be broken, this is most likely the reason why.
 
-To learn more about the considerations behind this removal, read the [Gatsby RFC](https://github.com/gatsbyjs/rfcs/blob/master/text/0002-remove-special-layout-components.md).
+To learn more about the considerations behind this removal, read the [RFC for removing the special layout component](https://github.com/gatsbyjs/rfcs/blob/master/text/0002-remove-special-layout-components.md).
 
 The following is the recommended migration path:
 
 ### 1. Convert children from function to normal prop (required)
+
 In v1, the `children` prop passed to layout was a function and needed to be executed. In v2, this is no longer the case.
 
-`layout in v1`
+Before:
 
 ```jsx
 import React from "react"
@@ -51,7 +50,7 @@ export default ({ children }) => (
 )
 ```
 
-`layout in v2`
+After:
 
 ```jsx{5}
 import React from "react"
@@ -64,11 +63,13 @@ export default ({ children }) => (
 ```
 
 ### 2. Move `layout/index.js` to `src/components/layout.js` (optional, but recommended)
+
 ```bash
 git mv src/layouts/index.js src/components/layout.js
 ```
 
 ### 3. Import and wrap pages with layout component
+
 Adhering to normal React composition model, you import the layout component and use it to wrap the content of the page.
 
 `src/pages/index.js`
@@ -87,10 +88,12 @@ export default () => (
 Repeat for every page and template that needs this layout.
 
 ### 4. Change query to use `StaticQuery`
-<!-- TODO: link StaticQuery text to StaticQuery doc page (if one will be made) -->
+
 Since layout is no longer special, you now need to make use of v2’s StaticQuery feature.
 
-`Query with layout in v1`
+> TODO: document StaticQuery and link to it from here
+
+Before:
 
 ```jsx
 import React, { Fragment } from "react"
@@ -116,7 +119,7 @@ export const query = graphql`
 `
 ```
 
-`StaticQuery with layout in v2`
+After:
 
 ```jsx
 import React, { Fragment } from "react"
@@ -146,6 +149,7 @@ export default ({ children }) => (
 ```
 
 ### 5. Pass `history`, `location`, and `match` props to layout
+
 In v1, layout component had access to `history`, `location`, and `match` props. In v2, only pages have access to these props; pass them to your layout component as needed.
 
 `layout`
@@ -175,22 +179,203 @@ export default props => (
 ```
 
 ## Rename `boundActionCreators` to `actions`
+
 `boundActionCreators` is deprecated in v2. You can continue using it, but it’s recommended that you rename it to `actions`.
 
+> TODO: document new actions - see [actions](/docs/actions)
+
 ## Rename `pathContext` to `pageContext`
+
 Similar to `boundActionCreators` above, `pathContext` is deprecated in favor of `pageContext`.
 
-<!--
-Taken from: https://github.com/gatsbyjs/gatsby/blob/v2/Breaking%20Changes.md
-* [] Remove postcss plugins (cssnext, cssimport) from default css loader config
-* [x] boundActionCreators => actions
-* [x] pathContext => pageContext
-* [] Source & transformer plugins now use UUIDs for ids. If you used glob or regex to query nodes by id then you'll need to query something else.
-* [] Mixed commonjs/es6 modules fail
-* [] Remove explicit polyfill and use the new builtins: usage support in babel 7.
-* [] Changed modifyBabelrc to onCreateBabelConfig
-* [] Changed modifyWebpackConfig to onCreateWebpackConfig
-* [] Inlining CSS changed — remove it from any custom html.js as done automatically by core now.
-* [x] Manually install react and react-dom, along with any dependencies required by your plugins.
-* [x] Layouts have been removed. To achieve the same behavior as v1, you have to wrap your pages and page templates with your own Layout component. Since Layout is a non-page component, making query has to be done with StaticQuery.
--->
+## Rename responsive image queries
+
+The `sizes` and `resolutions` queries are deprecated in v2. These queries have been renamed to `fluid` and `fixed` to make them easier to understand.
+
+Before:
+
+```jsx
+const Example = ({ data }) => {
+  <div>
+    <Img sizes={data.foo.childImageSharp.sizes} />
+    <Img resolutions={data.bar.childImageSharp.resolutions} />
+  </div>
+}
+
+export default Example
+
+export const pageQuery = graphql`
+  query IndexQuery {
+    foo: file(relativePath: { regex: "/foo.jpg/" }) {
+      childImageSharp {
+        sizes(maxWidth: 700) {
+          ...GatsbyImageSharpSizes_tracedSVG
+        }
+      }
+    }
+    bar: file(relativePath: { regex: "/bar.jpg/" }) {
+      childImageSharp {
+        resolutions(width: 500) {
+          ...GatsbyImageSharpResolutions_withWebp
+        }
+      }
+    }
+  }
+`
+```
+
+After:
+
+```jsx{3-4,14-15,21-22}
+const Example = ({ data }) => {
+  <div>
+    <Img fluid={data.foo.childImageSharp.fluid} />
+    <Img fixed={data.bar.childImageSharp.fixed} />
+  </div>
+}
+
+export default Example
+
+export const pageQuery = graphql`
+  query IndexQuery {
+    foo: file(relativePath: { regex: "/foo.jpg/" }) {
+      childImageSharp {
+        fluid(maxWidth: 700) {
+          ...GatsbyImageSharpFluid_tracedSVG
+        }
+      }
+    }
+    bar: file(relativePath: { regex: "/bar.jpg/" }) {
+      childImageSharp {
+        fixed(width: 500) {
+          ...GatsbyImageSharpFixed_withWebp
+        }
+      }
+    }
+  }
+`
+```
+
+Further examples can be found in the [Gatsby Image docs](https://github.com/gatsbyjs/gatsby/tree/d0e29272ed7b009dae18d35d41a45e700cdcab0d/packages/gatsby-image).
+
+## Manually specify postcss plugins
+
+Gatsby v2 removed `postcss-cssnext` and `postcss-import` from the default postcss setup.
+
+Use [`onCreateWebpackConfig`](/docs/add-custom-webpack-config) to specify your postcss plugins.
+
+Note: there will be a `postcss` plugin that allows you to configure postcss from a standard postcss config file. [Follow this discussion on issue 3284](https://github.com/gatsbyjs/gatsby/issues/3284).
+
+## Files mixing CommonJS with ES6 modules won't compile
+
+Gatsby v2 uses babel 7 which is stricter about parsing files with mixed JS styles.
+
+ES6 Modules are ok:
+
+```js
+import foo from "foo"
+export default foo
+```
+
+CommonJS is ok:
+
+```js
+const foo = require('foo');
+module.exports = foo;
+```
+
+Mixing `requires` and `export` is not ok:
+```js
+const foo = require('foo');
+export default foo
+```
+
+Mixing `import` and `module.exports` is not ok:
+```js
+import foo from "foo"
+module.exports = foo;
+```
+
+See [Gatsby's babel docs for more details](/docs/babel).
+
+## Don't query nodes by ID
+
+Source and transformer plugins now use UUIDs for IDs. If you used glob or regex to query nodes by id then you'll need to query something else.
+
+[See the Pull Request that implemented this change](https://github.com/gatsbyjs/gatsby/pull/3807/files)
+
+> TODO: add example
+
+## Remove explicit polyfills
+
+If your Gatsby v1 site included any polyfills, you can remove them. Gatsby v2 ships with babel 7 and is configured to automatically include polyfills for your code. See [Gatsby's babel docs for more details](/docs/babel).
+
+## Change `modifyBabelrc` to `onCreateBabelConfig`
+
+`modifyBabelrc` was renamed to [`onCreateBabelConfig`](/docs/node-apis/#modifyBabelrc) to bring it in line with the rest of Gatsby's API names.
+
+Before:
+
+```js
+exports.modifyBabelrc = ({ babelrc }) => {
+  return {
+    ...babelrc,
+    plugins: babelrc.plugins.concat([`foo`]),
+  }
+}
+```
+
+After:
+
+```js
+exports.onCreateBabelConfig = ({ actions }) => {
+  actions.setBabelPlugin({
+    name: `babel-plugin-foo`,
+  })
+}
+```
+
+Note usage of the new [`setBabelPlugin` action](/docs/actions/#setBabelPlugins).
+
+See [Gatsby's babel docs for more details](/docs/babel) about configuring babel.
+
+## Change `modifyWebpackConfig` to `onCreateWebpackConfig`
+
+`modifyWebpackConfig` was renamed to [`onCreateWebpackConfig`](/docs/node-apis/#onCreateWebpackConfig) to bring it in line with the rest of Gatsby's API names.
+
+Before:
+
+```js
+exports.modifyWebpackConfig = ({ config, stage }) => {
+  switch (stage) {
+    case `build-javascript`:
+      config.plugin(`Foo`, webpackFooPlugin, null)
+      break
+  }
+  return config
+}
+```
+
+
+After:
+
+```js
+exports.onCreateWebpackConfig = ({ stage, actions }) => {
+  switch (stage) {
+    case `build-javascript`:
+      actions.setWebpackConfig({
+        plugins: [webpackFooPlugin],
+      })
+  }
+}
+```
+
+Note usage of the new [`setWebpackConfig` action](/docs/actions/#setWebpackConfig).
+
+See [Gatsby's webpack docs for more details](/docs/add-custom-webpack-config) about configuring webpack.
+
+## CSS is inlined automatically
+
+Gatsby v2 automatically inlines CSS. Gatsby v1 required you to create a [custom `html.js` file](/docs/custom-html) to do this. You can remove any custom CSS inlining from your custom `html.js`, in many cases this allows you to completely remove your `html.js` file.
+
+See an example in [this PR that upgrades the `using-remark` site to Gatsby v2](https://github.com/gatsbyjs/gatsby/commit/765b679cbc222fd5f527690427ee431cca7ccd61#diff-637c76e3c059ed8efacedf6e30de2d61).