Merge branch 'master' into feature/gatsbyjs#6659

CODEOWNERS

@@ -3,17 +3,20 @@
 
 # These files have the highest likelihood to cause chaos, so we require an
 # admin to review and approve pull requests that affect these.
-/packages/gatsby/                               @gatsbyjs/admin
-/packages/babel-plugin-remove-graphql-queries/  @gatsbyjs/admin
-/packages/gatsby-link/                          @gatsbyjs/admin
-/packages/gatsby-dev-cli/                       @gatsbyjs/admin
-/packages/gatsby-cli/                           @gatsbyjs/admin
+/packages/gatsby/                               @gatsbyjs/core
+/packages/babel-plugin-remove-graphql-queries/  @gatsbyjs/core
+/packages/gatsby-link/                          @gatsbyjs/core
+/packages/gatsby-dev-cli/                       @gatsbyjs/core
+/packages/gatsby-cli/                           @gatsbyjs/core
 
 # We also need to be careful with CI/CD and repo config files.
-.circleci/                                      @gatsbyjs/admin
-.travis.yml                                     @gatsbyjs/admin
-appveyor.yml                                    @gatsbyjs/admin
-.github/                                        @gatsbyjs/admin
+.circleci/                                      @gatsbyjs/core
+.travis.yml                                     @gatsbyjs/core
+appveyor.yml                                    @gatsbyjs/core
+.github/                                        @gatsbyjs/core
+
+# The ecosystem files are error-prone, so we require an extra set of eyes on them.
+/docs/*                                         @gatsbyjs/ecosystem
 
 # The website auto-deploys, so we need an extra check to avoid shenanigans.
 /www/                                           @gatsbyjs/website

docs/blog/2018-09-17-gatsby-v2.md

@@ -75,7 +75,7 @@ The reductions are largely due to the hard work by libraries we rely on.
 
 The React team decreased their code size by 30% from React 15 to 16 (49.8kb to 34.8kb gzipped)
 
-We switched routers from react-router to @reach/router which brought a 25% smaller bundle (8kb to 6kb gzipped).
+We switched routers from react-router to @reach/router which brought a ~70% smaller bundle (18.4kb to 6kb gzipped).
 
 ### React 16
 

docs/blog/2018-09-25-announcing-graphql-stitching-support/index.md

@@ -0,0 +1,87 @@
+---
+title: Announcing support for natively querying 3rd-party GraphQL APIs with Gatsby
+date: "2018-09-25"
+author: "Mikhail Novikov"
+tags: ["graphql", "plugin", "source"]
+---
+
+When Gatsby was started 3.5 years ago, [GraphQL](https://www.graphql.com/) was still an internal project at Facebook and had yet to be open sourced.
+
+Since being open sourced, GraphQL's usage has exploded and [1000s of companies use it to power critical apps and websites](https://www.graphql.com/case-studies/).
+
+Gatsby's vision is to be the integration layer for modern websites gluing together data and code into highly performant websites and apps. GraphQL is integral to this vision.
+
+Gatsby v1 shipped last year with a plugin-powered data layer that let you easily pull data from any source using GraphQL. At the time, there was still very few public GraphQL schemas so we built a system that let plugins transform data from REST APIs into a GraphQL schema.
+
+But in the last year, a lot has changed. More and more services are shipping with native GraphQL APIs. CMSs like [GraphCMS](https://graphcms.com/), [AppSync](https://aws.amazon.com/appsync/), and [TakeShape](https://www.takeshape.io/) all have launched GraphQL APIs. [Contentful](https://www.contentful.com/) is launching a [native GraphQL API as well soon](https://www.contentful.com/blog/2018/07/04/graphql-abstract-syntax-tree-new-schema/).
+
+Watching the spread of GraphQL has all been incredibly exciting to watch and a fullfillment of our vision for the future of the web where sites easily stitch together data from many sources.
+
+But unfortunately, these new GraphQL APIs have been awkward to use inside Gatsby as you first had to wrap the API inside a Gatsby source plugin before you could query the data from your components.
+
+To fix this, [Gatsby 2.0](/blog/2018-09-17-gatsby-v2/) adds experimental support for schema stitching of external GraphQL APIs to its internal schema. Schema stitching allows merging multiple GraphQL schemas together, which greatly simplifies working with third-party GraphQL APIs. Along with low-level support for stitching in general, we are shipping an official [gatsby-source-graphql](https://www.gatsbyjs.org/packages/gatsby-source-graphql/) plugin, which enables connecting to an arbitrary GraphQL API with just a few lines of configuration!
+
+# Getting started
+
+Gatsby's data model is powered by an internal GraphQL API. It is a great abstraction that allows you to define the data requirements of your app, be it some files in the filesystem or a third-party API.
+
+Previously, when you wanted to add a 3rd-party GraphQL API, you needed to write a custom source plugin. But now, you simply add a small bit of config to your site's gatsby-config.js. The following example adds the Star Wars GraphQL API:
+
+```js
+// In your gatsby-config.js
+module.exports = {
+  plugins: [
+    {
+      resolve: "gatsby-source-graphql",
+      options: {
+        // This type will contain the remote schema Query type
+        typeName: "SWAPI",
+        // This is the field under which it's accessible
+        fieldName: "swapi",
+        // URL to query from
+        url: "https://api.graphcms.com/simple/v1/swapi",
+      },
+    },
+  ],
+}
+```
+
+After this you will have a field named `swapi` in your Gatsby GraphQL and you can query it.
+
+```graphql
+{
+  # Field name parameter defines how you can access third party API
+  swapi {
+    allSpecies {
+      name
+    }
+  }
+
+  # Other Gatsby querying works normally
+  site {
+    siteMetadata {
+      siteName
+    }
+  }
+}
+```
+
+# Why is it needed?
+
+To understand why a separate new plugin is needed, let's dive into how Gatsby source plugins work. Gatsby's GraphQL schema can be extended with source plugins. Source plugins can extend the schema by adding _nodes_ - objects that have some kind of global id. This way a `gatsby-source-filesystem` plugin can add all the files from a directory as nodes. Gatsby introspects the nodes that it gets and creates a GraphQL schema which you can use to fetch all those nodes.
+
+This system works really well for many cases and it's very intuitive, you don't need to care about creating a GraphQL schema or types for the nodes, any objects can be used. However, this is a limitation when using existing GraphQL APIs. First of all, you won't be able to use the same API as the one provided by the third-party API, because it will be replaced by Gatsby's internal node API. This can be confusing, because you can't consult the third-party API's documentation. Secondly, the plugin needs to proactively fetch all the possible data from the API, which can be complicated because the plugin author would have to predict which data might be needed.
+
+When there weren't many existing GraphQL APIs in the wild, that wasn't that much of a problem. For the few available APIs there was a source plugin. With the rise of both public GraphQL APIs, like GitHub or Shopify, and with so many more people having a GraphQL API of their own (or using one of the GraphQL solutions like Prisma, GraphCMS or AppSync), writing a plugin for each one became unfeasible. Meet `gatsby-source-graphql`.
+
+# How does it work?
+
+Instead of creating nodes for all potential items in a third-party API, `gatsby-source-graphql` uses schema stitching to combine the schema of a third-party API with the Gatsby schema. Schema stitching combines multiple GraphQL schemas into one, [read more about it here](https://www.apollographql.com/docs/graphql-tools/schema-stitching.html).
+
+The plugin puts the full third-party GraphQL API under one field in Gatsby's API. This way any types or fields of that API can be queried. There is no need to prefetch that data beforehand to create nodes, because the data will be fetched on-demand as required by the page queries.
+
+The actual stitching happens on the Gatsby level. There is a new action, [`addThirdPartySchema`](/docs/actions/#addThirdPartySchema), that can be used to add arbitrary schemas for stitching. It's a deliberately low-level API that we hope other plugin authors can use in the future to implement some mind-blowing GraphQL functionality.
+
+# Conclusions
+
+`gatsby-source-graphql` is part of [Gatsby's 2.0 release](/blog/2018-09-17-gatsby-v2/). Try it out now! [Check out the docs](/docs/third-party-graphql) or [a sample project using GitHub's GraphQL API](https://github.com/freiksenet/gatsby-github-displayer).

docs/blog/2018-09-27-reach-router/index.md

@@ -0,0 +1,65 @@
+---
+title: How we improved Gatsby's accessibility in v2 by switching to @reach/router
+date: 2018-09-27
+author: Amberley Romo
+tags: ["routing", "v2", "accessibility"]
+---
+
+We recently announced the [second major release of Gatsby](/blog/2018-09-17-gatsby-v2/) 🚀. One change we want to highlight is the switch to using [@reach/router](https://reach.tech/router) to improve the accessibility of routing in Gatsby sites. What is @reach/router, and what are the benefits of undertaking the switch?
+
+## What is @reach/router?
+
+@reach/router is a routing library for React written and maintained by one of the original creators of [react-router](https://github.com/ReactTraining/react-router), [Ryan Florence](https://twitter.com/ryanflorence). After [investigating the tradeoffs](https://github.com/gatsbyjs/gatsby/issues/5656), we made the leap to depending on @reach/router:
+
+- [Accessibility](https://reach.tech/router/accessibility) is a first-class concern
+- Smaller bundle size (~70% decrease, 18.4kb to 6kb gzipped)
+- Simplified API
+
+## How does it support accessibility?
+
+When you visit a Gatsby site, a static, server-rendered HTML page is loaded first, and then the JavaScript to hydrate the site into a web app is loaded. From there, internal routing is handled with the [Gatsby Link component](/docs/gatsby-link/), which wraps [@reach/router’s Link component](https://reach.tech/router/api/Link).
+
+Web apps rerender in the client -- without making a request to the server to fetch new HTML -- resulting in a faster, more seamless user experience. These performance benefits, however, can create a broken experience for users who rely on assistive technology like screen readers.
+
+When a user navigates between traditional server-rendered pages, the page is fully reloaded; In response, screen readers can announce the new content. When using most client-side routing solutions (out of the box), without the page reload, screen readers don’t know new content has been loaded to focus or announce.
+
+The video below demonstrates this challenge (Video by [Rob DeLuca](https://twitter.com/robdel12), which accompanied his related article, “[Single page app routers are broken](https://medium.com/@robdel12/single-page-apps-routers-are-broken-255daa310cf)”)
+
+<iframe width="560" height="315" src="https://www.youtube.com/embed/NKTdNv8JpuM?rel=0" frameborder="0" allow="autoplay; encrypted-media" allowfullscreen></iframe>
+
+A primary focus (no pun intended) of @reach/router is to manage focus in client-side routing, out of the box, lifting the onus from devs to manage it from scratch. From the @reach/router documentation:
+
+> Whenever the content of a page changes in response to a user interaction, the focus should be moved to that content; otherwise, users on assistive devices have to search around the page to find what changed–yuck! Without the help of a router, managing focus on route transitions requires a lot effort and knowledge on your part.
+
+> Reach Router provides out-of-the-box focus management so your apps are significantly more accessible without you breaking a sweat.
+
+> When the location changes, the top-most part of your application that changed is identified and focus is moved to it. Assistive devices then announce to the user the group of elements they are now focused on, similarly to how it works when they load up a page for the first time.
+
+The video below demonstrates this focus management:
+
+<blockquote class="twitter-tweet" data-conversation="none" data-lang="en"><p lang="en" dir="ltr">Check out that focus management 😍<br><br>The same code that makes this possible is what makes relative links and embedded routers possible too. <a href="https://t.co/DjqveMfspA">pic.twitter.com/DjqveMfspA</a></p>&mdash; Ryan Florence (@ryanflorence) <a href="https://twitter.com/ryanflorence/status/1002219535921889281?ref_src=twsrc%5Etfw">May 31, 2018</a></blockquote>
+
+In terms of the development experience with Gatsby, this change is mostly under the hood, folded into the implementation of the Gatsby Link component. In terms of usability, accessibility by default is a win for everyone 🙌🏻.
+
+## Migrating from v1 ➡️ v2
+
+For most sites, migrating from v1 to v2 shouldn’t be too painful, but there are a few instances you might want to be aware of. Check out the [v2 migration guide](/docs/migrating-from-v1-to-v2/#migrate-from-react-router-to-reachrouter) for details.
+
+## TLDR;
+
+[Smaller package + better accessibility + simplified APIs](https://github.com/gatsbyjs/gatsby/pull/6918) 👍
+
+We look forward to continuing to work actively with Ryan!
+
+<blockquote class="twitter-tweet" data-lang="en"><p lang="en" dir="ltr">Reach Router is hitting the big time with <a href="https://twitter.com/gatsbyjs?ref_src=twsrc%5Etfw">@gatsbyjs</a> adopting it and Nike shipping a site with it <a href="https://t.co/fthOUQ1lJh">https://t.co/fthOUQ1lJh</a>  :D<br><br>I&#39;ll be spending all day Thursday fixing/adding stuff Gatsby needs. AND! Gatsby is sponsoring my time.<br><br>Thanks <a href="https://twitter.com/kylemathews?ref_src=twsrc%5Etfw">@kylemathews</a> and the rest of the team 🙏🏽</p>&mdash; Ryan Florence (@ryanflorence) <a href="https://twitter.com/ryanflorence/status/1042117992140554241?ref_src=twsrc%5Etfw">September 18, 2018</a></blockquote>
+
+Related Gatsby docs:
+
+- [V2 Migration Guide](/docs/migrating-from-v1-to-v2/#migrate-from-react-router-to-reachrouter)
+- [Gatsby Link API reference](/docs/gatsby-link/)
+- [V2 announcement blog post](/blog/2018-09-17-gatsby-v2/)
+
+External references:
+
+- [Single page app routers are broken](https://medium.com/@robdel12/single-page-apps-routers-are-broken-255daa310cf) by Rob DeLuca
+- [@reach/router docs](https://reach.tech/router)