.circleci/config.yml

@@ -375,6 +375,17 @@ jobs:
           test_path: e2e-tests/gatsby-static-image
           test_command: yarn test
 
+  e2e_tests_visual-regression:
+    <<: *e2e-executor
+    steps:
+      - e2e-test:
+          test_path: e2e-tests/visual-regression
+          test_command: yarn test
+      - store_artifacts:
+          path: e2e-tests/visual-regression/__diff_output__
+      - store_test_results:
+          path: e2e-tests/visual-regression/cypress/results
+
   starters_validate:
     executor: node
     steps:
@@ -582,6 +593,8 @@ workflows:
           <<: *e2e-test-workflow
       - e2e_tests_gatsby-static-image:
           <<: *e2e-test-workflow
+      - e2e_tests_visual-regression:
+          <<: *e2e-test-workflow
       - e2e_tests_development_runtime:
           <<: *e2e-test-workflow
       - e2e_tests_production_runtime:

.eslintrc.js

@@ -175,10 +175,7 @@ module.exports = {
         // bump to @typescript-eslint/parser started showing Flow related errors in ts(x) files
         // so disabling them in .ts(x) files
         "flowtype/no-types-missing-file-annotation": "off",
-        "@typescript-eslint/array-type": [
-          'error',
-          { default: 'generic' },
-        ],
+        "@typescript-eslint/array-type": ["error", { default: "generic" }],
       },
     },
   ],

.github/ISSUE_TEMPLATE/config.yml

@@ -6,6 +6,9 @@ contact_links:
   - name: Gatsby Discord
     url: https://gatsby.dev/discord
     about: Ask questions, get help and discuss new things you're building with the Gatsby community
+  - name: Gatsby Discussions
+    url: https://github.com/gatsbyjs/gatsby/discussions
+    about: Have a question or feature request?
   - name: AskGatsbyJS Twitter
     url: https://twitter.com/AskGatsbyJS
     about: The official Twitter account to ask questions and get help with Gatsby

.jestSetup.js

@@ -1,2 +1 @@
 process.env.GATSBY_RECIPES_NO_COLOR = "true"
-process.env.GATSBY_EXPERIMENTAL_PLUGIN_OPTION_VALIDATION = "true"

benchmarks/gabe-csv-markdown/gatsby-node.js

@@ -42,21 +42,22 @@ exports.createPages = async ({ graphql, actions }) => {
   })
 }
 
+exports.unstable_shouldOnCreateNode = ({ node }) =>
+  node.internal.type === `GendataCsv`
+
 // Not sure if there is a better way than to create a proxy node for markdown to pick up
 // I certainly can't get remark to to pick up csv nodes :(
 exports.onCreateNode = ({ node, actions }) => {
   const { createNode } = actions
 
-  if (node.internal.type === `GendataCsv`) {
-    createNode({
-      id: `${node.id}-MarkdownProxy`,
-      parent: node.id,
-      internal: {
-        type: `MarkdownProxy`,
-        mediaType: "text/markdown",
-        content: node.articleContent,
-        contentDigest: node.articleContent,
-      },
-    })
-  }
+  createNode({
+    id: `${node.id}-MarkdownProxy`,
+    parent: node.id,
+    internal: {
+      type: `MarkdownProxy`,
+      mediaType: "text/markdown",
+      content: node.articleContent,
+      contentDigest: node.articleContent,
+    },
+  })
 }

benchmarks/gabe-fs-text/gatsby-node.js

@@ -40,40 +40,41 @@ exports.createPages = async ({ graphql, actions }) => {
   })
 }
 
-exports.onCreateNode = ({ node, actions , createNodeId}) => {
-  if (node.internal.type === "File") {
-    // Do minimal processing to get some key pieces. This could be gatsby-transformer-text or -html :p
+exports.unstable_shouldOnCreateNode = ({ node }) =>
+  node.internal.type === "File"
 
-    const html = fs.readFileSync(node.absolutePath, "utf8")
+exports.onCreateNode = ({ node, actions, createNodeId }) => {
+  // Do minimal processing to get some key pieces. This could be gatsby-transformer-text or -html :p
 
-    const base = path.basename(node.absolutePath)
-    const slug = base.slice(11, -5) // remove date prefix and `..txt` tail
-    const date = base.slice(0, 10)
+  const html = fs.readFileSync(node.absolutePath, "utf8")
 
-    const offset1 = html.indexOf("<h1>")
-    const title = html.slice(
-      offset1 + "<h1>".length,
-      html.indexOf("</h1>", offset1)
-    )
+  const base = path.basename(node.absolutePath)
+  const slug = base.slice(11, -5) // remove date prefix and `..txt` tail
+  const date = base.slice(0, 10)
 
-    const offset2 = html.indexOf("<blockquote>", offset1)
-    const description = html.slice(
-      offset2 + "<blockquote>".length,
-      html.indexOf("</blockquote>", offset2)
-    )
+  const offset1 = html.indexOf("<h1>")
+  const title = html.slice(
+    offset1 + "<h1>".length,
+    html.indexOf("</h1>", offset1)
+  )
 
-    actions.createNode({
-      id: createNodeId(slug),
-      slug,
-      date,
-      title,
-      description,
-      html,
-      internal: {
-        type: "Texto",
-        contentDigest: html,
-      },
-      parent: node.id, // Required otherwise the node is not cached and a warm build screws up. TODO: is touchNode faster?
-    })
-  }
+  const offset2 = html.indexOf("<blockquote>", offset1)
+  const description = html.slice(
+    offset2 + "<blockquote>".length,
+    html.indexOf("</blockquote>", offset2)
+  )
+
+  actions.createNode({
+    id: createNodeId(slug),
+    slug,
+    date,
+    title,
+    description,
+    html,
+    internal: {
+      type: "Texto",
+      contentDigest: html,
+    },
+    parent: node.id, // Required otherwise the node is not cached and a warm build screws up. TODO: is touchNode faster?
+  })
 }

dictionary.txt

@@ -172,7 +172,7 @@ Formik
 Formspree
 Formspree's
 FOUC
-FreeCodeCamp
+*freeCodeCamp
 frontend
 frontmatter
 Frontmatter
@@ -363,7 +363,7 @@ README
 reCAPTCHA
 reconciler
 Reddit
-redux
+*redux
 Redux
 rehydrate
 reimplement
@@ -425,6 +425,10 @@ subpage
 subprocesses
 subscribable
 Suriano
+*svg
+SVG
+*svgs
+SVGs
 symlink
 TalkYard
 theming
@@ -477,9 +481,9 @@ WebpackError
 webpage
 webpages
 websocket
-Wechat
+WeChat
 WeKnow
-Whatsapp
+WhatsApp
 workspaces
 www
 xyz

docs/contributing/translation/index.md

@@ -34,6 +34,6 @@ Each translation repo will have at least two maintainers and codeowners that are
 
 ## Language-specific channels
 
-Each translation group may want to have a space for maintainers and community members to ask questions and coordinate the project. **[Discord](https://gatsby.dev/discord) is the official channel** and maintainers can have their own private groups if desired. Some groups may elect to use a different platform such as Wechat or Whatsapp, but that will be at your own discretion.
+Each translation group may want to have a space for maintainers and community members to ask questions and coordinate the project. **[Discord](https://gatsby.dev/discord) is the official channel** and maintainers can have their own private groups if desired. Some groups may elect to use a different platform such as WeChat or WhatsApp, but that will be at your own discretion.
 
 To set up a Discord channel for a translation group (if it doesn't already exist), [ping the Gatsbyjs team](/contributing/how-to-contribute/#not-sure-how-to-start-contributing).

docs/docs/adding-a-shopping-cart-with-snipcart.md

@@ -190,5 +190,5 @@ The following quote is from the Snipcart [payment gateway page](https://app.snip
 - [OneShopper Gatsby starter](/starters/rohitguptab/OneShopper/)
 - Reference guide on [sourcing from Etsy](/docs/sourcing-from-etsy/)
 - Reference guide on [processing payments with Stripe](/docs/processing-payments-with-stripe/)
-- From the Snipcart blog: [E-Commerce for React Developers \[w/ Gatsby Tutorial\]](https://snipcart.com/blog/react-ecommerce-gatsby-tutorial)
+- From the Snipcart blog: [Gatsby E-Commerce Recipe: Integrate a Cart in a Few Steps](https://snipcart.com/blog/gatsby-recipes-ecommerce)
 - [Snipcart documentation](https://docs.snipcart.com/v3/setup/installation)

docs/docs/build-caching.md

@@ -40,15 +40,16 @@ The [Node API helpers](/docs/node-api-helpers/#cache) documentation offers more
 In your plugin's `gatsby-node.js` file, you can access the `cache` argument like so:
 
 ```js:title=gatsby-node.js
-exports.onPostBuild = async function ({ cache, store, graphql }, { query }) {
+exports.onPostBuild = async function ({ cache, graphql }, { query }) {
   const cacheKey = "some-key-name"
+  const twentyFourHoursInMilliseconds = 24 * 60 * 60 * 1000 // 86400000
   let obj = await cache.get(cacheKey)
 
   if (!obj) {
     obj = { created: Date.now() }
     const data = await graphql(query)
     obj.data = data
-  } else if (Date.now() > obj.lastChecked + 3600000) {
+  } else if (Date.now() > obj.lastChecked + twentyFourHoursInMilliseconds) {
     /* Reload after a day */
     const data = await graphql(query)
     obj.data = data

docs/docs/creating-and-modifying-pages.md

@@ -178,7 +178,7 @@ It does come with the advantage of querying your data from one place after decla
 
 However, it doesn’t give you the opportunity to know what exactly you are querying for in the template and if any changes occur in the component query structure in `gatsby-node.js`. [Hot reload](/docs/glossary#hot-module-replacement) is taken off the table and the site needs to be rebuilt for changes to reflect.
 
-Gatsby stores page metadata (including context) in a redux store (which also means that it stores the memory of the page). For larger sites (either number of pages and/or amount of data that is being passed via page context) this will cause problems. There might be "out of memory" crashes if it's too much data or degraded performance.
+Gatsby stores page metadata (including context) in a Redux store (which also means that it stores the memory of the page). For larger sites (either number of pages and/or amount of data that is being passed via page context) this will cause problems. There might be "out of memory" crashes if it's too much data or degraded performance.
 
 > If there is memory pressure, Node.js will try to garbage collect more often, which is a known performance issue.
 

docs/docs/data-storage-redux.md

@@ -16,7 +16,7 @@ The namespaces in Gatsby's Redux store are a great overview of the Gatsby intern
 - **Jobs** - Long-running and CPU-intensive processes, generally started as a side-effect to a GraphQL query. Gatsby doesn’t finish its process until all jobs are ended.
 - **webpack** - Config for the [webpack](/docs/webpack-and-ssr/) bundler which handles code optimization and splitting of delivered JavaScript bundles.
 
-The Gatsby [redux index file](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby/src/redux/index.ts) has two key exports, `store` and `emitter`. Throughout the bootstrap and build phases, `store` is used to get the current state and dispatch actions, while `emitter` is used to register listeners for particular actions. The store is also made available to Gatsby users through the [Node APIs](/docs/node-apis/).
+The Gatsby [Redux index file](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby/src/redux/index.ts) has two key exports, `store` and `emitter`. Throughout the bootstrap and build phases, `store` is used to get the current state and dispatch actions, while `emitter` is used to register listeners for particular actions. The store is also made available to Gatsby users through the [Node APIs](/docs/node-apis/).
 
 ## Actions
 

docs/docs/debugging-replace-renderer-api.md

@@ -51,7 +51,7 @@ You'll need to override your plugins' `replaceRenderer` code in your `gatsby-ssr
 
 ### Initial setup
 
-In this example project you're using [`redux`](https://github.com/gatsbyjs/gatsby/tree/master/examples/using-redux) and [Gatsby's Styled Components plugin](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-plugin-styled-components).
+In this example project you're using [Redux](https://github.com/gatsbyjs/gatsby/tree/master/examples/using-redux) and [Gatsby's Styled Components plugin](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-plugin-styled-components).
 
 ```js:title=gatsby-config.js
 module.exports = {

docs/docs/gatsby-lifecycle-apis.md

@@ -33,7 +33,7 @@ During the main bootstrap sequence, Gatsby (in this order):
   - within this, `createNode` can be called multiple times, which then triggers [onCreateNode](/docs/node-apis/#onCreateNode)
 - creates initial GraphQL schema
 - runs [resolvableExtensions](/docs/node-apis/#resolvableExtensions) which lets plugins register file types or extensions e.g. [`gatsby-plugin-typescript`](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby-plugin-typescript/src/gatsby-node.js)
-- runs [createPages](/docs/node-apis/#createPages) from the gatsby-node.js in the root directory of the project e.g. implemented by [`page-hot-reloader`](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby/src/bootstrap/page-hot-reloader.js)
+- runs [createPages](/docs/node-apis/#createPages) from the gatsby-node.js in the root directory of the project e.g. implemented by [`page-hot-reloader`](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby/src/bootstrap/page-hot-reloader.ts)
   - within this, `createPage` can be called any number of times, which then triggers [onCreatePage](/docs/node-apis/#onCreatePage)
 - runs [createPagesStatefully](/docs/node-apis/#createPagesStatefully)
 - runs source nodes again and updates the GraphQL schema to include pages this time

docs/docs/graphql-concepts.md

@@ -158,7 +158,7 @@ Gatsby will create a schema that looks something like this:
 title: String
 ```
 
-This makes it easy to pull data from anywhere and immediately start writing
+This makes it possible to pull data from anywhere and immediately start writing
 GraphQL queries against your data.
 
 This _can_ cause confusion as some data sources allow you to define

docs/docs/graphql-reference.md

@@ -85,7 +85,7 @@ In this query `filter` and the `ne` (not equals) operator is used to show only r
 
 Gatsby relies on [Sift](https://www.npmjs.com/package/sift) to enable MongoDB-like query syntax for object filtering. This allows Gatsby to support operators like `eq`, `ne`, `in`, `regex` and querying nested fields through the `__` connector.
 
-It is also possible to filter on multiple fields - just separate the individual filters by a comma (works as an AND):
+It is also possible to filter on multiple fields by separating the individual filters by a comma (works as an AND):
 
 ```js
 filter: { contentType: { in: ["post", "page"] }, draft: { eq: false } }

docs/docs/graphql.md

@@ -26,7 +26,12 @@ Which returns this:
 }
 ```
 
-Notice how the query signature exactly matches the returned JSON signature. This is possible because in GraphQL, you query against a `schema` that is the representation of your available data. Don't worry about where the schema comes from right now, Gatsby takes care of organizing all of your data for you and making it discoverable with a tool called GraphiQL. GraphiQL is a UI that lets you 1) run queries against your data in the browser, and 2) dig into the structure of data available to you through a data type explorer.
+Notice how the query signature exactly matches the returned JSON signature. This is possible because in GraphQL, you query against a `schema` that is the representation of your available data. Don't worry about where the schema comes from right now, Gatsby takes care of organizing all of your data for you and making it discoverable with a tool called GraphiQL.
+
+GraphiQL is a UI that lets you:
+
+1. Run queries against your data in the browser;
+2. Dig into the structure of data available to you through a data type explorer.
 
 If you want to know more about GraphQL, you can read more about [why Gatsby uses it](/docs/why-gatsby-uses-graphql/) and check out this [conceptual guide](/docs/graphql-concepts/) on querying data with GraphQL.
 

docs/docs/how-code-splitting-works.md

@@ -167,7 +167,7 @@ If the asset is CSS, you [inject it inline in the head](https://github.com/gatsb
 
 #### Prefetching chunks
 
-As shown above, Gatsby uses "preload" to speed up loading of resources required by the page. These are its CSS and its core JavaScript needed to run the page. But if you stopped there, then when a user clicked a link to another page, he would have to wait for that pages resources to download before showing it. To speed this up, once the current page has loaded, Gatsby looks for all links on the page, and for each starts prefetching the page that the link points to.
+As shown above, Gatsby uses "preload" to speed up loading of resources required by the page. These are its CSS and its core JavaScript needed to run the page. But if you stopped there, then when a user clicked a link to another page, they would have to wait for that pages resources to download before showing it. To speed this up, once the current page has loaded, Gatsby looks for all links on the page, and for each starts prefetching the page that the link points to.
 
 It does this using the `<link rel="prefetch" href="..." />` parameter. When the browser sees this tag, it will start downloading the resource but at an extremely low priority and only when the resources for the current page have finished loading. Check out the [MDN prefetch docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Link_prefetching_FAQ) for more.
 

docs/docs/how-gatsby-works-with-github-pages.md

@@ -2,7 +2,7 @@
 title: How Gatsby Works with GitHub Pages
 ---
 
-GitHub Pages is a service offered by GitHub that allows hosting for websites configured straight from the repository. A Gatsby site can be hosted on GitHub Pages with just a few configurations to the codebase and the repository's settings.
+GitHub Pages is a service offered by GitHub that allows hosting for websites configured straight from the repository. A Gatsby site can be hosted on GitHub Pages with a few configurations to the codebase and the repository's settings.
 
 You can publish your site on GitHub Pages several different ways: