Skip to content

Latest commit

 

History

History
164 lines (100 loc) · 9.12 KB

CONTRIBUTING.md

File metadata and controls

164 lines (100 loc) · 9.12 KB
Raw

Contributing to graphql.org

This repository is governed by the GraphQL Code of Conduct. By contributing, you agree to abide by its terms.

Thanks for taking the time to contribute! The GraphQL community is great because of people like you 🎉

There are many ways to get involved. Follow this guide and feel free to reach out if you have questions.

What's in this document

Development guide

Running the site locally

First, clone this repository and move into the directory:

git clone https://github.com/graphql/graphql.github.io.git
cd graphql.github.io

Then, use Yarn to install and load all the necessary dependencies:

yarn

Note: Yarn is currently the only way to run the site locally.

Run the start script to launch the server:

yarn start

Finally, open http://localhost:8000 to view it in the browser.

The GraphQL website is built with Gatsby. This means that a hot-reloading development environment will be accessible by default.

Branching

Active development for graphql.org happens on the source branch. Be sure to create any new branches or direct any pull requests back to source.

Project structure

  • static: Files that will be copied directly to public.
  • public: Output files that will be served by a static HTTP server.
  • src: Markdown and the TypeScript/JavaScript files used to generate the website.
    • assets: All the less files that contain stylesheets.
    • components and Containers: React components used for layouts and pages.
    • content: Markdown files with the content of pages.
    • templates: Layout templates.
    • utils: Helper functions.

Publishing the updated site

Your changes will be merged into the source branch. Then, the CI will automatically publish a new version of http://graphql.org via Netlify.

Updating content

Fix a typo, code sample bug, or formatting

If you notice something wrong in the text or code samples, please follow our development guide to open a pull request with your fix.

All of the content on graphql.org is written and formatted in Markdown.

Add a library, tool, or service to the Code page

The Code page is a collection of libraries, tools, and services built for GraphQL.

General guidelines

Adding a resource:

  • With rare exceptions, any pull request that adds a new library, tool, or service to the Code page will be accepted.
  • Any library should include a few paragraphs describing the usage and offering people a chance to grok the project priorities.
  • If there isn't a section already for your programming language, please add it.

If it isn't a library, tool, or service - then it could go on the Community page. If you aren't sure where your resource would fit, you can open an issue and ask.

Removing a resource:

  • Services that don't work anymore
  • Code repositories that are archived
  • Projects declared to be abandoned by their maintainers
  • Any link that 404s

We rely on these concrete signals before removing a resource. Even if a project hasn't been released in a few years, that doesn't mean that it's not working.

Workflow

To add or remove a resource to this page, follow our development guide to open a pull request.

The content for this page is located in various directories under src/content/code. Everything is written and formatted in Markdown.

Add a resource to the Community page

The Community page highlights resources and groups that help people get more involved with GraphQL.

To add something to this page, follow our development guide to open a pull request.

The content for this page is located in a directory under src/content/community. Everything is written and formatted in Markdown.

Add a question to the FAQ

Our Frequently Asked Questions (FAQ) page is designed to help answer questions from the community. This page is still in development, so if you think there's a question missing - please open an issue! It'd be great if you could include both the question and a proposed answer outline in the issue description.

Once you have approval from a maintainer, use the development guide to add your question and answer. The content for the FAQ is located in src/content/faq. Each section has its own Markdown file.

Note: All answers in this section should be vendor-neutral and accessible to GraphQL users of all levels.

When your answer is ready, open a pull request.

Write a new section or guide

There are still several Best Practices guides that no one has written yet. If you want to take one of these, comment on the original issue and mention which topic you'll work on.

Then, use our development guide to determine where your new page best fits. Our documentation is written and formatted in Markdown.

Once it's ready for review, please open a pull request.

Making changes to the code

Before diving into any code updates, please open an issue describing the change(s) you'd like to make.

If you're working off an existing issue, follow our development guide to make your changes. Once it's ready for review, please open a pull request and reference the original issue.

Browser support

We aim to support the latest stable versions of Chrome, Edge, Firefox, Safari, and Safari on mobile.

Contributing something else

Interested in adding something not covered in this guide? Please open an issue and tell us all about your idea.

Asking questions

If you run into any problems or have questions while contributing, you're always welcome to open an issue.

Opening a PR to contribute your code

You can also ping our team in the #website channel on the GraphQL Slack. Get your invite here!

This repository is managed by EasyCLA. Project participants must sign the free (GraphQL Specification Membership agreement before making a contribution. You only need to do this one time, and it can be signed by individual contributors or their employers.

To initiate the signature process please open a PR against this repo. The EasyCLA bot will block the merge if we still need a membership agreement from you.

You can find detailed information here. If you have issues, please email [email protected].

If your company benefits from GraphQL and you would like to provide essential financial support for the systems and people that power our community, please also consider membership in the GraphQL Foundation.