chore(docs): Update Contributing section, RFC process, Governance Mod…

…el (#34900)

Co-authored-by: Ty Hopp <[email protected]>

.github/ISSUE_TEMPLATE/BUG_REPORT.yml

@@ -89,7 +89,7 @@ body:
   - type: textarea
     attributes:
       label: Config Flags
-      description: Do you use any "flags" inside "gatsby-config.js"? If yes, please paste them here.
+      description: Do you use any "flags" inside "gatsby-config"? If yes, please paste them here.
       placeholder: |
         For example:
 

.github/workflows/schedule-stale.yml

@@ -23,15 +23,15 @@ jobs:
 
             We get a lot of issues, so we currently close issues after 60 days of inactivity. It’s been at least 20 days since the last update here.
             If we missed this issue or if you want to keep it open, please reply here.
-            As a friendly reminder: the best way to see this issue, or any other, fixed is to open a Pull Request. Check out [gatsby.dev/contribute](https://www.gatsbyjs.com/contributing/how-to-contribute/) for more information about opening PRs, triaging issues, and contributing!
+            As a friendly reminder: the best way to see this issue, or any other, fixed is to open a Pull Request. Check out [gatsby.dev/contribute](https://www.gatsbyjs.com/contributing#how-to-contribute) for more information about opening PRs, triaging issues, and contributing!
 
             Thanks for being a part of the Gatsby community! 💪💜
           close-issue-message: |
             Hey again!
 
             It’s been 60 days since anything happened on this issue, so our friendly neighborhood robot (that’s me!) is going to close it.
             Please keep in mind that I’m only a robot, so if I’ve closed this issue in error, I’m `HUMAN_EMOTION_SORRY`. Please feel free to comment on this issue or create a new one if you need anything else.
-            As a friendly reminder: the best way to see this issue, or any other, fixed is to open a Pull Request. Check out [gatsby.dev/contribute](https://www.gatsbyjs.com/contributing/how-to-contribute/) for more information about opening PRs, triaging issues, and contributing!
+            As a friendly reminder: the best way to see this issue, or any other, fixed is to open a Pull Request. Check out [gatsby.dev/contribute](https://www.gatsbyjs.com/contributing#how-to-contribute) for more information about opening PRs, triaging issues, and contributing!
 
             Thanks again for being part of the Gatsby community! 💪💜
           stale-issue-label: "stale?"

CONTRIBUTING.md

@@ -1,3 +1,3 @@
-## How to Contribute
+# Contributing to Gatsby
 
-For information related to contributing to Gatsby, please check out the [How to Contribute](https://www.gatsbyjs.com/contributing/how-to-contribute/) section of the documentation at the Gatsby site.
+For information related to contributing to Gatsby, please check out the [Contributing to Gatsby](https://www.gatsbyjs.com/contributing/) section of the documentation at the Gatsby site.

GOVERNANCE.md

@@ -0,0 +1,3 @@
+# Governance
+
+Please check out the [Governance Model](https://www.gatsbyjs.com/contributing/gatsby-governance-model/) page on the Gatsby site.

docs/contributing/blog-contributions.md

@@ -23,7 +23,6 @@ Things we’re looking for in Gatsby blog content:
 
 - Information to help others overcome challenges you’ve faced while working with Gatsby
 - Stories about how Gatsby helped you overcome different challenges on work and personal projects
-- Gatsby case studies
 - Showcasing a tool, fix, or other content you or someone else have contributed to Gatsby’s open source community
 - Showcasing a tool, fix, or other content someone else has contributed to Gatsby’s open source community
 - Clear and thoughtful explanations of technical details or complex concepts related to React, GraphQL, web and application development, open-source contribution, Gatsby core, and other Gatsby-adjacent subject matter

docs/contributing/code-contributions.md

@@ -2,110 +2,96 @@
 title: Code Contributions
 ---
 
-The beauty of contributing to open source is that you can clone your favorite project, get it running locally, and test out experiments and changes in real time! Way to feel like a wizard.
+The beauty of contributing to open source is that you can clone your favorite project, get it running locally, and test out experiments and changes in real time! You get the opportunity to participate in a community while feeling a wizard doing it. For instructions on contributing to the docs, visit the [docs contributions page](/contributing/docs-contributions/).
 
-## Repo setup
+Gatsby uses a "monorepo" pattern to manage its many dependencies and relies on [Lerna](https://lerna.js.org/) and [Yarn](https://yarnpkg.com/) to configure the repository for both active development and documentation infrastructure changes.
 
-This page includes details specific to the Gatsby core and ecosystem codebase.
+Yarn is a package manager for your code, similar to [npm](https://www.npmjs.com/). While npm is used to develop Gatsby sites with the CLI, contributing to the Gatsby repo requires Yarn for the following reason: we use Yarn's [workspaces](https://yarnpkg.com/lang/en/docs/workspaces/) feature that comes really handy for monorepos. It allows us to install dependencies from multiple `package.json` files in sub-folders, enabling a faster and lighter installation process.
 
-To start setting up the Gatsby repo on your machine using git, Yarn and Gatsby-CLI, check out the page on [setting up your local dev environment](/contributing/setting-up-your-local-dev-environment/).
+## Setting up your local dev environment
 
-Alternatively, you can skip the local setup and [use an online dev environment](/contributing/using-an-online-dev-environment/).
+### Install Node and Yarn
 
-To contribute to the blog, check out the setup steps on the [blog contributions](/contributing/blog-contributions/) page. For instructions on contributing to the docs, visit the [docs contributions page](/contributing/docs-contributions/).
+- Ensure you have the latest **LTS** version of Node installed (`>= 14.15.0`) by executing `node --version`
+- [Install](https://yarnpkg.com/en/docs/install) the Yarn package manager.
+- Ensure you have the version 1 of Yarn installed (`^1`) by executing `yarn --version`. The Gatsby monorepo does not yet support later versions of Yarn.
 
-## Creating your own plugins and loaders
+### Fork, clone, and branch the repository
 
-If you create a loader or plugin, we would love for you to open source it and put it on npm. For more information on creating custom plugins, please see the documentation for [plugins](/docs/plugins/) and the [API specification](/docs/api-specification/).
+- [Fork](https://help.github.com/en/github/getting-started-with-github/fork-a-repo) the [official `gatsbyjs/gatsby` repository](https://github.com/gatsbyjs/gatsby).
+- Clone your fork: `git clone https://github.com/<your-username>/gatsby.git`
+- Set up repo and install dependencies: `yarn run bootstrap`
+- Create a topic branch: `git checkout -b topics/new-feature-name`
+- Run `yarn run watch` from the root of the repo to watch for changes to packages' source code and compile these changes on-the-fly as you work.
+  - Note that the watch command can be resource intensive. To limit it to the packages you're working on, add a scope flag, like `yarn run watch --scope={gatsby,gatsby-cli}`.
+  - To watch just one package such as `gatsby`, run `yarn run watch --scope=gatsby`.
 
-## Contributing example sites
+> **Note:** Optionally you can run `git clone --depth=1 https://github.com/<your-username>/gatsby.git` to do a shallow clone (smaller download size) rather than a deep clone, however this sometimes leads to problems when you want to reference older upstream branches.
 
-Gatsby's policy is that "Using" example sites (like those in the [examples part of the repo](https://github.com/gatsbyjs/gatsby/tree/master/examples)) should only be around plugins that are maintained by the core team as it's hard to keep things up to date otherwise.
+### Testing out changes in an example project
 
-To contribute example sites, it is recommended to create your own GitHub repo and link to it from your source plugin, etc.
-
-## Using Docker to set up test environments
-
-With all of the possible Gatsby integrations, it might help to spin up a Docker container with the software application you need to test. This makes installation a breeze, so you can focus less on getting set up and more on the integration details that matter to you.
-
-> Do you have a setup not listed here? Let us know by adding it to this file and opening a PR.
-
-### Docker, WordPress and Gatsby
-
-To install WordPress to use with Gatsby, this `docker-compose.yml` file will come in handy:
-
-```yaml:title=docker-compose.yml
-version: "2"
-
-services:
-  db:
-    image: mysql:5.6
-    container_name: sessions_db
-    ports:
-      - "3306:3306"
-    volumes:
-      - "./.data/db:/var/lib/mysql"
-    restart: always
-    environment:
-      MYSQL_ROOT_PASSWORD: wordpress
-      MYSQL_DATABASE: wordpress
-      MYSQL_USER: wordpress
-      MYSQL_PASSWORD: wordpress
-
-  wordpress:
-    image: wordpress:latest
-    container_name: sessions_wordpress
-    depends_on:
-      - db
-    links:
-      - db
-    ports:
-      - "7000:80"
-    restart: always
-    environment:
-      WORDPRESS_DB_HOST: db:3306
-      WORDPRESS_DB_PASSWORD: wordpress
-    volumes:
-      - ./wp-content:/var/www/html/wp-content
-      - ./wp-app:/var/www/html
-
-  phpmyadmin:
-    image: phpmyadmin/phpmyadmin
-    container_name: sessions_phpmyadmin
-    environment:
-      - PMA_ARBITRARY=1
-      - PMA_HOST=sessions_db
-      - PMA_USER=wordpress
-      - PMA_PASSWORD=wordpress
-    restart: always
-    ports:
-      - 8080:80
-    volumes:
-      - /sessions
-```
-
-Use the above file contents when following the Docker WordPress install instructions: https://docs.docker.com/compose/wordpress/
-
-Using Docker Compose, you can start and stop a WordPress instance and integrate it with the [Gatsby WordPress source plugin](/docs/sourcing-from-wordpress/).
-
-## Development tools
-
-### Debugging the build process
+- Install [gatsby-dev-cli](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-dev-cli):
+  - Make sure you have the Gatsby Dev CLI installed with `gatsby-dev -v`
+  - If not, install globally: `yarn global add gatsby-dev-cli`
+  - Run `gatsby-dev --set-path-to-repo /path/to/my/forked/version/gatsby` to point `gatsby-dev-cli` to your fork
+- Run `yarn install` in each of the sites you're testing.
+- For each of your Gatsby test sites, run the `gatsby-dev` command inside the test site's directory to copy
+  the built files from your cloned copy of Gatsby. It'll watch for your changes
+  to Gatsby packages and copy them into the site. For more detailed instructions
+  see the [gatsby-dev-cli README](https://www.npmjs.com/package/gatsby-dev-cli) and check out the [gatsby-dev-cli demo video](https://www.youtube.com/watch?v=D0SwX1MSuas).
+  - To copy files from just one package such as `gatsby`, run `gatsby-dev --packages gatsby`
+  - Note: If you plan to modify packages that are exported from `gatsby` directly, you need to either add those manually to your test sites so that they are listed in `package.json` (e.g. `yarn add gatsby-link`), or specify them explicitly with `gatsby-dev --packages gatsby-link`).
+- If you've recently run `gatsby-dev` your `node_modules` will be out of sync with current published packages. In order to undo this, you can remove the `node_modules` directory, revert any changes to `package.json` and lockfiles, and reinstall modules with `npm install` or `yarn install` . Alternatively, you can run:
 
-Check [Debugging the build process](/docs/debugging-the-build-process/) page to learn how to debug Gatsby.
+  ```shell
+  git checkout package.json; yarn --force
+  ```
+
+### Add tests
+
+- Add tests and code for your changes.
+  - Begin by adding unit tests with Jest.
+  - If you want to test out this feature in a more real-world application you can also consider adding [integration tests](https://github.com/gatsbyjs/gatsby/tree/master/integration-tests) and [end-to-end tests](https://github.com/gatsbyjs/gatsby/tree/master/e2e-tests).
+  - If you're unsure on how to add tests or which types of test, ask in a comment in the pull request
+- Once you're done, make sure all unit tests still pass: `yarn test`.
+  - To run tests for a single package you can run: `yarn jest <package-name>`.
+  - To run a single test file you can run: `yarn jest <file-path>`.
+  - Once you push your changes to GitHub, the CI will run tests in a controlled environment and might uncover failures on e.g. different type of machines (Linux vs. Windows)
+
+If you're adding e2e tests and want to run them against local changes:
+
+- In the root of the monorepo, run `yarn lerna run build --scope=<package-name>` where `package-name` is the directory containing the changes you're testing.
+- Run `gatsby-dev` inside your specific e2e test directory, for example `e2e-tests/themes/development-runtime`.
+- While the previous step is running, open a new terminal window and run `yarn test` in that same e2e test directory.
+
+### Troubleshooting
+
+At any point during the contributing process the Gatsby team would love to help! For help with a specific problem you can [open an Discussion on GitHub](https://github.com/gatsbyjs/gatsby/discussions/categories/help). Or drop in to [our Discord server](https://gatsby.dev/discord) for general community discussion and support.
 
-## Official theme development
+- When you went through the initial setup some time ago and now want to contribute something new, you should make sure to [sync your fork](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/syncing-a-fork) with the latest changes from the primary branch on [gatsbyjs/gatsby](https://github.com/gatsbyjs/gatsby). Otherwise, you might run into issues where files are not found as they were renamed, moved, or deleted.
+- After syncing your fork, run `yarn run bootstrap` to compile all packages. When files or tests depend on the build output (files in `/dist` directories) they might fail otherwise.
+- Make sure to run `yarn run watch` on the packages' source code you're changing.
 
-This section is for official theme development. If you are looking
-to build your own theme, see [building themes](/docs/themes/building-themes/).
+## How to open a pull request
 
-Themes live in their own [repo](https://github.com/gatsbyjs/themes). The themes themselves live in the `packages` directory and starters using them are in the `starters` directory. In order to work on a theme, find the starter that uses it and do the following:
+If you've made all your changes, added tests, and want to contribute your changes to Gatsby, you can head over to the [How to open a pull request documentation](/contributing/how-to-open-a-pull-request) to learn more.
 
-1. Run `yarn` in your terminal in the root of the repo.
-2. Still in the repo root, run `yarn workspace <starter name> develop`.
+## Other contributions
 
-From there, you can make changes in the theme and see them reflected in the running site.
+### Creating your own plugins
+
+If you create a loader or plugin, we would love for you to open source it and put it on npm. For more information on creating custom plugins, please see the documentation for [plugins](/docs/plugins/) and the [API specification](/docs/api-specification/).
+
+### Contributing example sites
+
+Gatsby's policy is that "Using" example sites (like those in the [examples part of the repo](https://github.com/gatsbyjs/gatsby/tree/master/examples)) should only be around plugins that are maintained by the core team as it's hard to keep things up to date otherwise.
+
+To contribute example sites, it is recommended to create your own GitHub repo and link to it from your source plugin, etc. You can also create a starter project and submit it to the [starter showcase](/starters/submissions).
+
+## Debugging the build process
+
+Check [Debugging the build process](/docs/debugging-the-build-process/) page to learn how to debug Gatsby.
 
 ## Feedback
 
-At any point during the contributing process the Gatsby team would love to help! For help with a specific problem you can [open an issue on GitHub](/contributing/how-to-file-an-issue/). Or drop in to [our Discord server](https://gatsby.dev/discord) for general community discussion and support.
+At any point during the contributing process the Gatsby team would love to help! For help with a specific problem you can [open an Discussion on GitHub](https://github.com/gatsbyjs/gatsby/discussions/categories/help). Or drop in to [our Discord server](https://gatsby.dev/discord) for general community discussion and support.

docs/contributing/code-of-conduct.md

@@ -44,7 +44,4 @@ When faced with repeated bad faith comments or harassment after an earnest attem
 
 ## Attribution
 
-This Code of Conduct is adapted from the Contributor Covenant, version 1.4.
-
-- homepage: https://contributor-covenant.org
-- version: https://contributor-covenant.org/version/1/4/
+This Code of Conduct is adapted from the [Contributor Covenant](https://contributor-covenant.org), [version 1.4](https://contributor-covenant.org/version/1/4/).