title |
---|
How to Contribute |
We want contributing to Gatsby to be fun, enjoyable, and educational for anyone and everyone. Contributions go far beyond pull requests and commits; we are thrilled to receive a variety of other contributions including the following:
- Blogging, speaking about, or creating tutorials about one of Gatsby's many features. Mention @gatsbyjs on Twitter and/or email shannon [at] gatsbyjs [dot] com so we can give pointers and tips (if you want them 😄) and help you spread the word. Please add your blog posts and videos of talks to our Awesome Gatsby page.
- Submitting new feature ideas through an RFC
- Submitting new documentation; titles in italics on gatsbyjs.org are stubs and need contributions
- Tweeting about things you #buildwithgatsby (make sure to use the hashtag and/or @ mention us!)
- Submitting documentation updates, enhancements, designs, or bugfixes
- Submitting spelling or grammar fixes
- Adding unit or functional tests
- Triaging GitHub issues -- especially determining whether an issue still persists or is reproducible
- Reporting bugs or issues
- Searching for Gatsby on Discord or Spectrum and helping someone else who needs help
- Teaching others how to contribute to Gatsby's repo!
As our way of saying “thank you” to our contributors, all contributors are eligible for free Gatsby swag — whether you’re contributing code, docs, a talk, an article, or something else that helps the Gatby community. Learn how to claim free swag for contributors.
If you are worried or don't know where to start, you can always reach out to Shannon Soper (@shannonb_ux) on Twitter or submit an issue and a maintainer can help give you guidance!
Looking to speak about Gatsby? We'd love to review your talk abstract/CFP! You can email it to shannon [at] gatsbyjs [dot] com, and we can give pointers or tips!
If you create a loader or plugin, we would <3 for you to open source it and put it on npm. For more information on creating custom plugins, please see the documentation for plugins and the API specification.
Gatsby uses a "monorepo" pattern to manage its many dependencies and relies on lerna and yarn to configure the repository for active development.
We're currently gearing up to release a new major version, v2.
During this time, please choose the correct branch for your pull request:
master
branch for Gatsby version 2 bug fixesmaster
branch for any new features (these will be released in the Gatsby v2 betas)master
branch for updates to thewww
anddocs
directoriesv1
branch for Gatsby version 1 bug fixes
Note: We will only accept bug fixes for Gatsby v1. New features should be added to Gatsby v2.
You can install the latest version of Gatsby by following these steps:
- Clone the repo, navigate to its directory.
- ensure you have the latest version of yarn installed (>= 1.0.2) https://yarnpkg.com/en/docs/install
- Install dependencies using
yarn run bootstrap
in the root of the repo.
The usual contributing steps are:
- Fork the official repository.
- Clone your fork:
git clone --depth=1 https://github.com/<your-username>/gatsby.git
- Setup up repo and install dependencies:
yarn run bootstrap
- Make sure tests are passing for you:
yarn test
- Create a topic branch:
git checkout -b topics/new-feature-name
- Run
npm 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, likenpm run watch -- --scope={gatsby,gatsby-cli}
. To watch just one package, runnpm run watch -- --scope=gatsby
. - Install gatsby-dev-cli globally:
yarn global add gatsby-dev-cli
- Run
yarn install
in each of the sites you're testing. - For each of your Gatsby test sites, run the
gatsby-dev
command there 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 - Add tests and code for your changes.
- Once you're done, make sure all tests still pass:
yarn test
. - Commit and push to your fork.
- Create a pull request from your branch.
Gatsby, unsurprisingly, uses Gatsby for its documentation website.
If you want to add/modify any Gatsby documentation, go to the docs folder on GitHub and use the file editor to edit and then preview your changes. GitHub then allows you to commit the change and raise a PR right in the UI. This is the easiest way you can contribute to the project!
However, if you want to make more changes to the website, that is, change layouts, add sections/pages, follow the steps below. You can then spin up your own instance of the Gatsby website and make/preview your changes before raising a pull request.
- Clone the repo and navigate to
/www
- Run
yarn
to install all of the website's dependencies. - Run
gatsby develop
to preview the website inhttp://localhost:8000
- The Markdown files for the documentation live in
/docs
folder. Make additions or modifications here. - Make sure to double check your grammar and capitalise correctly.
- Commit and push to your fork.
- Create a pull request from your branch.
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 or contacting @gatsbyjs on Twitter.
To add a new blog post to the gatsbyjs.org blog:
- Clone the Gatsby repo and navigate to
/www
- Run
yarn
to install all of the website's dependencies. - Run
gatsby develop
to preview the blog athttp://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 anindex.md
file. - Add
title
,date
,author
, andtags
(view existing tags or add a new one) to the frontmatter of yourindex.md
. If you are cross posting your post you can addcanonicalLink
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 -
/docs/how-to-contribute
instead ofhttps://gatsbyjs.org/docs/how-to-contribute
- Double check your grammar and capitalise correctly
- Commit and push to your fork
- Create a pull request from your branch
Gatsby uses Redux for managing state during development and building. It's often helpful to see the flow of actions and built-up state for a site you're working on or if adding new functionality to core. We leverage Remote Redux Devtools and RemoteDev Server to help you debug Gatsby.
To use this, first install
redux-devtools-extension
in your browser. Then in your Gatsby repo, run npm run remotedev
. Then in your
site directory run REDUX_DEVTOOLS=true gatsby develop
. Depending on your
operating system and shell, you may need to modify how you set the
REDUX_DEVTOOLS
environment variable.
At this point, your site will be sending Redux actions and state to the remote server.
To connect to this, you need to setup the devtools extension to talk to the remote server.
First open the remote devtools.
Then click settings along the bottom menu and set the host and port.
After this, the devtools extension should connect to the remote server and you'll see actions start showing up.
Warning!! Lots of bugginess. While having this available is extremely helpful, this setup is very buggy and fragile. There is a memory leak in the extension that's triggered it seems every time you restart the Gatsby development server. Also the extension often, for no apparent reason, just won't show any actions from the remote server. It'll also often freeze up. The best solution seems to just be turning everything off and on again. Fixing up these tools would be very helpful for us and many others using these tools if someone wants to take this on!