[www] Add 'Upgrading to v2' docs page

[m-allanson]

Create an Upgrading to Gatsby v2 guide.

• Manually install react and react-dom, along with any dependencies required by your plugins.
• 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.
• boundActionCreators => actions
• pathContext => pageContext
• Deprecated responsive image query names
• Remove postcss plugins (cssnext, cssimport) from default css loader config
• Mixed commonjs/es6 modules fail
• 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.
• 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.
• Add instructions on converting layouts for sites with many pages (Refer to Add gatsby-plugin-layout docs to v2 migration post #5753)

[KyleAMathews]

@jquense created this file to collect breaking changes which I've adding to as well https://github.com/gatsbyjs/gatsby/blob/v2/Breaking%20Changes.md

Once the first beta is out, I'm going to solicit public v1 sites to upgrade and start writing a upgrading docs page from that.

[tomByrer]

I found this post helpful for an overview:
https://www.gatsbycentral.com/getting-started-with-gatsby-v2

[ryanditjia]

Hi guys, is there currently a RouterContext sort of thing, that exposes history, location, and match props?

While upgrading Gatsby’s www to v2, as well as a client site, I found having to pass history or location to Layout to be somewhat a pain, a sentiment shared by @jquense here.

I’m not sure of the implications of such an API, but being able to do this:

import { RouterContext } from 'gatsby'

const Layout = ({ children }) => (
  <RouterContext.Consumer>
    {({ location, history, match }) => (
      // ...rest of code
    )}
  </RouterContext.Consumer>
)

will help a lot of people migrate faster.

Another question I have: should sizes and resolutions’ change to fluid and fixed be documented as breaking instead of deprecation? From what I saw, gatsby-source-contentful will be moving to fluid and fixed exclusively.

[KyleAMathews]

I believe you could just wrap your layout component with withRouter https://github.com/ReactTraining/react-router/blob/master/packages/react-router/docs/api/withRouter.md

fluid/fixed isn't a breaking change. If sizes/resolutions were removed from gatsby-source-contentful, we should restore them.

[m-allanson]

I'm going to close this as the bulk of the work is done. I don't think the remaining item should block releasing a v2 beta. I've created a new issue for docs on updating pages with layouts for larger sites: #5753