-
Notifications
You must be signed in to change notification settings - Fork 10.3k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: new section for contributing (#11812)
## Description As per [rfc/29](gatsbyjs/rfcs#29), this PR introduces a major change to the Gatsby docs: a new `/contributing` section. I did a big find and replace to update all links, and there are also redirects for pages that moved. This is a pretty large PR, and I welcome any and all feedback on the new structure and content. My only request is that we try to resolve any feedback quickly so that community PRs aren't working on outdated stuff. Here's a screenshot of the new Contributing landing page:  ## Related Issues Fixes #11803, Fixes #8847 ## Outstanding questions - Do we need to make any additional changes to CODEOWNERS? - I included a link to `/contributing` in the docs sidebar to ease the transition. Should the link use some kind of icon to distinguish that it takes the user away from the docs? - Should we add a new icon to the mobile nav (I didn't make any mobile changes in this PR)? - Any changes to the sidebar, specifically around accordions? ## Subsequent related issues/stubs - Gatsby Governance Model: #11805 - Triaging GitHub Issues: #11810
- Loading branch information
1 parent
62172be
commit d14137c
Showing
96 changed files
with
861 additions
and
350 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,3 +1,3 @@ | ||
| ## How to Contribute | ||
|
|
||
| For information related to contributing to Gatsby, please check out the [How to Contribute](https://www.gatsbyjs.org/docs/how-to-contribute/) section of the documentation at the Gatsby site. | ||
| For information related to contributing to Gatsby, please check out the [How to Contribute](https://www.gatsbyjs.org/contributing/how-to-contribute/) section of the documentation at the Gatsby site. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,65 @@ | ||
| --- | ||
| title: Blog & Website Contributions | ||
| --- | ||
|
|
||
| We wholeheartedly welcome contributions to the Gatsby blog and website! Instructions on this page: | ||
|
|
||
| - [Contributing to the blog](#contributing-to-the-blog) | ||
| - [Blog post format](#blog-post-format) | ||
| - [Making changes to the website](#making-changes-to-the-website) | ||
|
|
||
| ## Contributing to the blog | ||
|
|
||
| Note: Before adding a blog post ensure you have approval from a member of the Gatsby team. You can do this by [opening an issue](https://github.com/gatsbyjs/gatsby/issues/new/choose) or contacting [@gatsbyjs on Twitter](https://twitter.com/gatsbyjs). | ||
|
|
||
| To add a new blog post to the gatsbyjs.org blog: | ||
|
|
||
| - Clone [the Gatsby repo](https://github.com/gatsbyjs/gatsby/) and navigate to `/www` | ||
| - Run `yarn` to install all of the website's dependencies. ([Why Yarn?](/contributing/setting-up-your-local-dev-environment#using-yarn)) | ||
| - Run `npm run develop` to preview the blog at `http://localhost:8000/blog`. | ||
| - The content for the blog lives in the `/docs/blog` folder. Make additions or modifications here. | ||
| - Add your avatar image to `/docs/blog/avatars` | ||
| - Add your name to `/docs/blog/author.yaml` | ||
| - Add a new folder following the pattern `/docs/blog/yyyy-mm-dd-title`. Within this newly created folder add an `index.md` file. | ||
| - Add `title`, `date`, `author`, and `tags` ([view existing tags](https://www.gatsbyjs.org/blog/tags/) or add a new one) to the frontmatter of your `index.md`. If you are cross posting your post you can add `canonicalLink` for SEO benefits. You can check the other blog posts in `/docs/blog` for examples. | ||
| - If your blog post contains images add them to your blog post folder and reference them in your post's `index.md`. | ||
| - Ensure any links to gatsbyjs.org are relative links - `/contributing/how-to-contribute/` instead of `https://gatsbyjs.org/contributing/how-to-contribute` | ||
| - Follow the [Style Guide](https://www.gatsbyjs.org/contributing/gatsby-style-guide/#word-choice) to make sure you're using the appropriate wording. | ||
| - Double check your grammar and capitalise correctly | ||
| - Commit and push to your fork | ||
| - Create a pull request from your branch | ||
| - We recommend using a prefix of `docs`, e.g. `docs/your-change` or `docs-your-change` ([PR example](https://github.com/gatsbyjs/gatsby/commit/9c21394add7906974dcfd22ad5dc1351a99d7ceb#diff-bf544fce773d8a5381f64c37d48d9f12)) | ||
|
|
||
| ### Blog post format | ||
|
|
||
| The following format can help you in creating your new blog content. At the top is "frontmatter", a fancy name for metadata in Markdown; the frontmatter for your post should include a title, date, singular author name (for now, we would welcome issues/PRs for this), and one or more tags. Your content will follow, after the second set of dashes (`---`). | ||
|
|
||
| ```md | ||
| --- | ||
| title: "Your Great Blog Post" | ||
| date: YYYY-MM-DD | ||
| author: John Doe | ||
| tags: | ||
| - awesome | ||
| - post | ||
| --- | ||
|
|
||
| Your next great blog post awaits! | ||
|
|
||
| Include images by creating a folder for your post and including | ||
| Markdown and image files for easy linking. | ||
|
|
||
|  | ||
| ``` | ||
|
|
||
| ## Making changes to the website | ||
|
|
||
| If you want to make changes, improvements, or add new functionality to the website: like with the blog, you don't have to set up the full Gatsby repo to contribute. You can spin up your own instance of the Gatsby website with these steps: | ||
|
|
||
| - Clone [the Gatsby repo](https://github.com/gatsbyjs/gatsby/) and navigate to `/www` | ||
| - Run `yarn` to install all of the website's dependencies. | ||
| - Run `npm run develop` to preview the blog at `http://localhost:8000/blog`. | ||
|
|
||
| Now you can make and preview your changes before raising a pull request! | ||
|
|
||
| For full repo setup instructions, visit the [code contributions](/contributing/code-contributions/) page. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,111 @@ | ||
| --- | ||
| 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. | ||
|
|
||
| On this page: | ||
|
|
||
| - [Repo setup](#repo-setup) | ||
| - [Creating your own plugins and loaders](#creating-your-own-plugins-and-loaders) | ||
| - [Making changes to the starter Library](#making-changes-to-the-starter-library) | ||
| - [Using Docker to set up test environments](#using-docker-to-set-up-test-environments) | ||
| - [Development tools](#development-tools) | ||
|
|
||
| ## Repo setup | ||
|
|
||
| This page includes details specific to the Gatsby core and ecosystem codebase. | ||
|
|
||
| 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/). | ||
|
|
||
| To contribute to the blog or Gatsbyjs.org website, check out the setup steps on the [blog and website contributions](/contributing/blog-and-website-contributions/) page. For instructions on contributing to the docs, visit the [docs contributions page](/contributing/docs-contributions/). | ||
|
|
||
| ## Creating your own plugins and loaders | ||
|
|
||
| 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/). | ||
|
|
||
| ## Making changes to the starter library | ||
|
|
||
| Note: You don't need to follow these steps to submit to the starter library. This is only necessary if you'd like to contribute to the functionality of the starter library. To submit a starter, [follow these steps instead](/contributing/submit-to-starter-library/). | ||
|
|
||
| To develop on the starter library, you'll need to supply a GitHub personal access token. | ||
|
|
||
| 1. Create a personal access token in your GitHub [Developer settings](https://github.com/settings/tokens). | ||
| 2. In the new token's settings, grant that token the "public_repo" scope. | ||
| 3. Create a file in the root of `www` called `.env.development`, and add the token to that file like so: | ||
|
|
||
| ```text:title=.env.development | ||
| GITHUB_API_TOKEN=YOUR_TOKEN_HERE | ||
| ``` | ||
|
|
||
| The `.env.development` file is ignored by git. Your token should never be committed. | ||
|
|
||
| ## 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: | ||
|
|
||
| ``` | ||
| 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 | ||
|
|
||
| Check [Debugging the build process](/docs/debugging-the-build-process/) page to learn how to debug Gatsby. |
File renamed without changes.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,23 @@ | ||
| --- | ||
| title: Community Contributions | ||
| --- | ||
|
|
||
| A big part of what makes Gatsby great is each and every one of you in the community. Your contributions enrich the Gatsby experience and make it better every day. | ||
|
|
||
| We welcome all contributions from you in the community, and would be thrilled to amplify your voice. Contributions are not limited to code, and can take all shapes and forms: | ||
|
|
||
| - Your wonderful Gatsby.js website! | ||
| - Gatsby starters | ||
| - Gatsby plugins | ||
| - Blog posts and case studies | ||
| - Talk and lecture videos | ||
| - Workshop materials | ||
| - Github issues and pull requests | ||
|
|
||
| ...and anything else you can think of. Our showcase and library contribution docs are a great place to start: | ||
|
|
||
| - [Submit to Site Showcase](/contributing/submit-to-site-showcase/) | ||
| - [Submit to Starter Library](/contributing/submit-to-starter-library/) | ||
| - [Submit to Plugin Library](/contributing/submit-to-plugin-library/) | ||
|
|
||
| Peruse through the rest of our contributor docs and reach out to us on [Twitter](https://twitter.com/gatsbyjs), [Discord](https://gatsby.app/discord), or in a [GitHub issue](/contributing/how-to-file-an-issue/) if you have any questions about contributing! |
Oops, something went wrong.