From c02b8f9cb1d8fe3c4622666764fb0e9902d7efa0 Mon Sep 17 00:00:00 2001
From: Ryandi Tjia <ryandi.tjia@gmail.com>
Date: Mon, 28 May 2018 16:12:18 +0700
Subject: [PATCH 1/3] v1 to v2 migration guide doc start

---
 docs/docs/migrating-from-v1-to-v2.md | 196 +++++++++++++++++++++++++++
 1 file changed, 196 insertions(+)
 create mode 100644 docs/docs/migrating-from-v1-to-v2.md

diff --git a/docs/docs/migrating-from-v1-to-v2.md b/docs/docs/migrating-from-v1-to-v2.md
new file mode 100644
index 0000000000000..d5ac0c905b461
--- /dev/null
+++ b/docs/docs/migrating-from-v1-to-v2.md
@@ -0,0 +1,196 @@
+---
+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.
+
+```bash
+npm i react react-dom
+```
+
+or
+
+```bash
+yarn add react react-dom
+```
+
+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.
+
+```bash
+npm i typography react-typography
+```
+
+or
+
+```bash
+yarn add typography react-typography
+```
+
+Search for the plugins that you use in [Gatsby’s plugins page](/plugins) and check their installation instructions.
+
+## 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).
+
+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`
+
+```jsx
+import React from "react"
+
+export default ({ children }) => (
+  <div>
+    {children()}
+  </div>
+)
+```
+
+`layout in v2`
+
+```jsx{5}
+import React from "react"
+
+export default ({ children }) => (
+  <div>
+    {children}
+  </div>
+)
+```
+
+### 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`
+
+```jsx
+import React from "react"
+import Layout from "../components/layout"
+
+export default () => (
+  <Layout>
+    <div>Hello World</div>
+  </Layout>
+)
+```
+
+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`
+
+```jsx
+import React, { Fragment } from "react"
+import Helmet from "react-helmet"
+
+export default ({ children, data }) => (
+  <Fragment>
+    <Helmet titleTemplate={`%s | ${data.site.siteMetadata.title}`} defaultTitle={data.site.siteMetadata.title} />
+    <div>
+      {children()}
+    </div>
+  </Fragment>
+)
+
+export const query = graphql`
+  query LayoutQuery {
+    site {
+      siteMetadata {
+        title
+      }
+    }
+  }
+`
+```
+
+`StaticQuery with layout in v2`
+
+```jsx
+import React, { Fragment } from "react"
+import { StaticQuery } from "gatsby"
+
+export default ({ children }) => (
+  <StaticQuery
+    query={graphql`
+      query LayoutQuery {
+        site {
+          siteMetadata {
+            title
+          }
+        }
+      }
+    `}
+    render={data => (
+      <Fragment>
+        <Helmet titleTemplate={`%s | ${data.site.siteMetadata.title}`} defaultTitle={data.site.siteMetadata.title} />
+        <div>
+          {children}
+        </div>
+      </Fragment>
+    )}
+  />
+)
+```
+
+### 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`
+
+```jsx
+import React from "react"
+
+export default ({ children, location }) => (
+  <div>
+    <p>Path is {location.pathname}</p>
+    {children}
+  </div>
+)
+```
+
+`src/pages/index.js`
+
+```jsx
+import React from "react"
+import Layout from "../components/layout.js"
+
+export default props => (
+  <Layout location={props.location}>
+    <div>Hello World</div>
+  </Layout>
+)
+```
+
+## Rename `boundActionCreators` to `actions`
+`boundActionCreators` is deprecated in v2. You can continue using it, but it’s recommended that you rename it to `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.
+-->

From 9654d0e10dc495ac81b3dfea01f843a40ebc2574 Mon Sep 17 00:00:00 2001
From: Ryandi Tjia <ryandi.tjia@gmail.com>
Date: Mon, 28 May 2018 16:12:50 +0700
Subject: [PATCH 2/3] Add sidebar link to v2 migration guide

---
 www/src/pages/docs/doc-links.yaml | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/www/src/pages/docs/doc-links.yaml b/www/src/pages/docs/doc-links.yaml
index 802c1d24a8a2b..7deba610845c7 100644
--- a/www/src/pages/docs/doc-links.yaml
+++ b/www/src/pages/docs/doc-links.yaml
@@ -58,6 +58,8 @@
       link: /docs/netlify-cms/
     - title: How Gatsby Works with GitHub Pages
       link: /docs/how-gatsby-works-with-github-pages/
+    - title: Migrating from v1 to v2
+      link: /docs/migrating-from-v1-to-v2/
     - title: Migrating from v0 to v1
       link: /docs/migrating-from-v0-to-v1/
     - title: Path Prefix

From f6676adc6912d7b658941ae4f38a7b6dfe3a8ef4 Mon Sep 17 00:00:00 2001
From: Ryandi Tjia <ryandi.tjia@gmail.com>
Date: Mon, 28 May 2018 20:54:46 +0700
Subject: [PATCH 3/3] Update README to show v1 to v2 migration guide

---
 README.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/README.md b/README.md
index 1a991af3df76b..c385c9765f439 100644
--- a/README.md
+++ b/README.md
@@ -220,6 +220,8 @@ Websites built with Gatsby:
 
 **[View the docs on gatsbyjs.org](https://www.gatsbyjs.org/docs/)**
 
+[Migrating from v1 to v2?](https://www.gatsbyjs.org/docs/migrating-from-v1-to-v2/)
+
 [Migrating from v0 to v1?](https://www.gatsbyjs.org/docs/migrating-from-v0-to-v1/)
 
 [v0 docs](https://github.com/gatsbyjs/gatsby/blob/v0.12.48/docs/index.md)