How to Open a Pull Request

A big part of contributing to open source is submitting changes to a project: improvements to source code or tests, updates to docs content, even typos or broken links. This doc will cover what you need to know to open a pull request in Gatsby.

What is a Pull Request (PR)?

In case you aren’t familiar, here’s how the folks at GitHub define a pull request:

Pull requests let you tell others about changes you’ve pushed to a branch in a repository on GitHub. Once a pull request is opened, you can discuss and review the potential changes with collaborators and add follow-up commits before your changes are merged into the base branch.

Gatsby uses the PR process to review and test changes before they’re added to Gatsby’s GitHub repository. Anyone can open a pull request. The same process is used for all contributors, whether this is your first open source contribution or you’re a core member of the Gatsby team.

When someone wants to contribute to Gatsby, they open a request to pull their code into the repo. Depending on the type of change, PRs are categorized into:

Recommendations for different kinds of contributions will follow in this guide and throughout the contributing docs.

Things to know before opening a PR

We typically recommend opening an issue before a pull request if there isn’t already an issue for the problem you’d like to solve. This helps facilitate a discussion before deciding on an implementation.

For some changes, such as typo fixes or broken links, it may be appropriate to open a small PR by itself. This is somewhat subjective so if you have any questions, feel free to ask us.

The Gatsby core team uses a triaging process outlined in Managing Pull Requests, if you’re interested in learning more about how that works.

Opening PRs in Gatsby

For any kind of change to files in the Gatsby repo, you can follow the below steps. Be sure to check out additional tips for contributing to various parts of the repo later in this doc, such as docs changes, blog posts, starters, or code improvements and tests.

To test changes locally against the Gatsby site and project files, fork the repo and install parts of it to run on your local machine.

  • Fork and clone the Gatsby repo.

  • Install yarn to pull in dependencies and build the project.

  • Follow the instructions for the part of the project you want to change. (See specific sections below.)

  • Create a branch in Git to isolate your changes:

  • Once you have changes in Git you want to push, add them and create a commit. For information on how to structure your commits, check out the Managing PRs doc.

    • Using a dot character . will add all untracked files in the current directory and subdirectories.
    • Using a visual tool like GitHub Desktop or GitX can help for choosing which files and lines to commit.

  • Committing code will run the automated linter using Prettier. To run the linter manually, run an npm script in the project’s base directory:

  • Commit any linting changes before pushing by amending the previous commit or by adding a new commit. For more on linting and tests, visit the Managing PRs doc.

  • Push your changes to your fork, assuming it is set up as origin:

  • To open a PR with your changes against the Gatsby repo, you can use the GitHub Pull Request UI. Alternatively, you can use the command line: we recommend hub for that.

Documentation PRs

The Gatsby.js docs site mostly lives in the www and docs directories on GitHub, including docs and tutorial content. There are also some examples in the Gatsby repo referenced in the docs.

Additional docs PR steps:

  • For docs-only changes, consider using git checkout -b docs/some-change or git checkout -b docs-some-change, as this will short circuit the CI process and only run linting tasks.

Further instructions can be found on the docs contributions page.

Code changes

Instructions for making changes to the Gatsby source code, tests, internals, APIs, packages, and more can be found in the contributing docs on setting up your local dev environment. There are also additional details on the Code contributions page.

Starters or Site Showcase

Note: Showcase and starter contributions are currently paused while the Gatsby team develops a new workflow for sharing your Gatsby sites with the community.

Blog posts

For the Gatsby blog, it’s necessary to run your content idea by the Gatsby team before submitting it. For more information, refer to the page on blog contributions, including how to propose an idea and setting up the blog to run locally.

Follow up with reviews and suggestions

After a PR is sent to the Gatsby GitHub repo, the Gatsby core team and the community may suggest modifications to the changes that your PR introduces.

Depending on what type of change is proposed, some combination of the Gatsby Core, Themes, Developer Relations, and Product Marketing teams review and approve every PR that the community sends to make sure that it meets the contribution guidelines of the repo, and to find opportunities for improvement to your PR changes.

These suggestions may also be called “request changes” by the GitHub UI. When a change request is added to your PR, this and the rest of the change requests will appear on the GitHub page for your PR. From this page you can use the suggestions UI to:

For suggestions that may not be resolved using the GitHub UI, remember that you can keep adding related commits to your PR before it is merged and those commits will also be a part of such PR.

After all your questions have been resolved and the requested changes have been committed, you can mark the conversation as solved.

This process helps both the Gatsby team and the community to contribute with improvements for your changes before they are merged into the Gatsby GitHub repo.

Update your fork with the latest Gatsby changes

The Gatsby GitHub repo is very active, so it’s likely you’ll need to update your fork with the latest changes to be able to merge in your code. This requires adding Gatsby as an upstream remote:

  • Set Gatsby’s repo URL as a remote source. The name of the remote is arbitrary; this example uses upstream.
  • You can verify the remote name and URL at any time:
  • Fetch the latest changes from Gatsby:
  • In the branch you want to update, merge any changes from Gatsby into your fork:
    • If there are any merge conflicts, you’ll want to address those to get a clean merge.
  • Once your branch is in good working order, push the changes to your fork:

For more information on working with upstream repos, visit the GitHub docs.

Additional resources

Edit this page on GitHub