|
| 1 | +# Contributing to graphql.org |
| 2 | + |
| 3 | +> This repository is governed by the [GraphQL Code of Conduct](https://graphql.org/codeofconduct/). By contributing, you agree to abide by its terms. |
| 4 | +
|
| 5 | +Thanks for taking the time to contribute! The GraphQL community is great because of people like you 🎉 |
| 6 | + |
| 7 | +There are many ways to get involved. Follow this guide and feel free to [reach out if you have questions](#asking-questions). |
| 8 | + |
| 9 | +## What's in this document |
| 10 | + |
| 11 | +- [Development guide](#development-guide) |
| 12 | + - [Running the site locally](#running-the-site-locally) |
| 13 | + - [Branching](#branching) |
| 14 | + - [Project structure](#project-structure) |
| 15 | + - [Publishing the updated site](#publishing-the-updated-site) |
| 16 | +- [Updating content](#updating-content) |
| 17 | + - [Fix a typo, code sample bug, or formatting](#fix-a-typo-code-sample-bug-or-formatting) |
| 18 | + - [Add a library or tool to the Code page](#add-a-library-or-tool-to-the-code-page) |
| 19 | + - [Add a resource to the Community page](#add-a-resource-to-the-community-page) |
| 20 | + - [Add a question to the FAQ](#add-a-question-to-the-faq) |
| 21 | + - [Write a new section or guide](#write-a-new-section-or-guide) |
| 22 | +- [Making changes to the code](#making-changes-to-the-code) |
| 23 | + - [Browser support](#browser-support) |
| 24 | +- [Contributing something else](#contributing-something-else) |
| 25 | +- [Asking questions](#asking-questions) |
| 26 | + |
| 27 | +## Development guide |
| 28 | + |
| 29 | +### Running the site locally |
| 30 | + |
| 31 | +First, clone this repository and move into the directory: |
| 32 | + |
| 33 | +```bash |
| 34 | +git clone https://github.com/graphql/graphql.github.io.git |
| 35 | +cd graphql.github.io |
| 36 | +``` |
| 37 | + |
| 38 | +Then, use [Yarn](https://yarnpkg.com/getting-started/install) to install and load all the necessary dependencies: |
| 39 | + |
| 40 | +```bash |
| 41 | +yarn |
| 42 | +``` |
| 43 | + |
| 44 | +> Note: [Yarn is currently the only way to run the site locally](https://github.com/graphql/graphql.github.io/issues/946). |
| 45 | +
|
| 46 | +Run the `start` script to launch the server: |
| 47 | + |
| 48 | +```bash |
| 49 | +yarn start |
| 50 | +``` |
| 51 | + |
| 52 | +Finally, open [http://localhost:8000](http://localhost:8000) to view it in the browser. |
| 53 | + |
| 54 | +The GraphQL website is built with [Gatsby](https://www.gatsbyjs.com/docs/). This means that a hot-reloading development environment will be accessible by default. |
| 55 | + |
| 56 | +### Branching |
| 57 | + |
| 58 | +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`. |
| 59 | + |
| 60 | +### Project structure |
| 61 | + |
| 62 | +- `static`: Files that will be copied directly to `public`. |
| 63 | +- `public`: Output files that will be served by a static HTTP server. |
| 64 | +- `src`: Markdown and the TypeScript/JavaScript files used to generate the website. |
| 65 | + - `assets`: All the [`less`](http://lesscss.org/) files that contain stylesheets. |
| 66 | + - `components` and `Containers`: React components used for layouts and pages. |
| 67 | + - `content`: Markdown files with the content of pages. |
| 68 | + - `templates`: Layout templates. |
| 69 | + - `utils`: Helper functions. |
| 70 | + |
| 71 | +### Publishing the updated site |
| 72 | + |
| 73 | +Your changes will be merged into the `source` branch. Then, the CI will automatically publish a new version of http://graphql.org via [Netlify](https://docs.netlify.com/). |
| 74 | + |
| 75 | +## Updating content |
| 76 | + |
| 77 | +### Fix a typo, code sample bug, or formatting |
| 78 | + |
| 79 | +If you notice something wrong in the text or code samples, please follow our [development guide](#development-guide) to [open a pull request](https://github.com/graphql/graphql.github.io/pulls) with your fix. |
| 80 | + |
| 81 | +All of the content on graphql.org is written and formatted in [Markdown](https://www.gatsbyjs.com/docs/mdx/markdown-syntax/). |
| 82 | + |
| 83 | +### Add a library, tool, or service to the Code page |
| 84 | + |
| 85 | +The [Code page](https://graphql.org/code/) is a collection of libraries, tools, and services built for GraphQL. |
| 86 | + |
| 87 | +#### General guidelines |
| 88 | + |
| 89 | +**Adding a resource:** |
| 90 | +- With rare exceptions, any pull request that adds a new library, tool, or service to the Code page will be accepted. |
| 91 | +- Any library should include a few paragraphs describing the usage and offering people a chance to grok the project priorities. |
| 92 | +- If there isn't a section already for your programming language, please add it. |
| 93 | + |
| 94 | +If it isn't a library, tool, or service - then it could go on the [Community page](#add-a-resource-to-the-community-page). If you aren't sure where your resource would fit, you can [open an issue](https://github.com/graphql/graphql.github.io/issues/new) and ask. |
| 95 | + |
| 96 | +**Removing a resource:** |
| 97 | +- Services that don't work anymore |
| 98 | +- Code repositories that are archived |
| 99 | +- Projects declared to be abandoned by their maintainers |
| 100 | +- Any link that 404s |
| 101 | + |
| 102 | +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. |
| 103 | + |
| 104 | +#### Workflow |
| 105 | + |
| 106 | +To add or remove a resource to this page, follow our [development guide](#development-guide) to [open a pull request](https://github.com/graphql/graphql.github.io/pulls). |
| 107 | + |
| 108 | +The content for this page is located in [various directories under `src/content/code`](./src/). Everything is written and formatted in [Markdown](https://www.gatsbyjs.com/docs/mdx/markdown-syntax/). |
| 109 | + |
| 110 | +### Add a resource to the Community page |
| 111 | + |
| 112 | +The [Community page](https://graphql.org/community/) highlights resources and groups that help people get more involved with GraphQL. |
| 113 | + |
| 114 | +To add something to this page, follow our [development guide](#development-guide) to [open a pull request](https://github.com/graphql/graphql.github.io/pulls). |
| 115 | + |
| 116 | +The content for this page is located in a [directory under `src/content/community`](./src/). Everything is written and formatted in [Markdown](https://www.gatsbyjs.com/docs/mdx/markdown-syntax/). |
| 117 | + |
| 118 | +### Add a question to the FAQ |
| 119 | + |
| 120 | +Our [Frequently Asked Questions (FAQ) page](https://graphql.org/faq/) 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](https://github.com/graphql/graphql.github.io/issues/new)! It'd be great if you could include both the question and a proposed answer outline in the issue description. |
| 121 | + |
| 122 | +Once you have approval from a maintainer, use the [development guide](#development-guide) to add your question and answer. The content for the FAQ is located in [`src/content/faq`](./src/content/faq/). Each section has its own [Markdown](https://www.gatsbyjs.com/docs/mdx/markdown-syntax/) file. |
| 123 | + |
| 124 | +> Note: All answers in this section should be vendor-neutral and accessible to GraphQL users of all levels. |
| 125 | +
|
| 126 | +When your answer is ready, [open a pull request](https://github.com/graphql/graphql.github.io/pulls/). |
| 127 | + |
| 128 | +### Write a new section or guide |
| 129 | + |
| 130 | +There are still several [Best Practices guides that no one has written](https://github.com/graphql/graphql.github.io/issues/41) yet. If you want to take one of these, comment on [the original issue](https://github.com/graphql/graphql.github.io/issues/41) and mention which topic you'll work on. |
| 131 | + |
| 132 | +Then, use our [development guide](#development-guide) to determine where your new page best fits. Our documentation is written and formatted in [Markdown](https://www.gatsbyjs.com/docs/mdx/markdown-syntax/). |
| 133 | + |
| 134 | +Once it's ready for review, please [open a pull request](https://github.com/graphql/graphql.github.io/pulls/). |
| 135 | + |
| 136 | +## Making changes to the code |
| 137 | + |
| 138 | +Before diving into any code updates, please [open an issue](https://github.com/graphql/graphql.github.io/issues/new) describing the change(s) you'd like to make. |
| 139 | + |
| 140 | +If you're working off an [existing issue](https://github.com/graphql/graphql.github.io/issues/), follow our [development guide](#development-guide) to make your changes. Once it's ready for review, please [open a pull request](https://github.com/graphql/graphql.github.io/pulls/) and reference the original issue. |
| 141 | + |
| 142 | +### Browser support |
| 143 | + |
| 144 | +We aim to support the latest stable versions of Chrome, Edge, Firefox, Safari, and Safari on mobile. |
| 145 | + |
| 146 | +## Contributing something else |
| 147 | + |
| 148 | +Interested in adding something not covered in this guide? Please [open an issue](https://github.com/graphql/graphql.github.io/issues/new) and tell us all about your idea. |
| 149 | + |
| 150 | +## Asking questions |
| 151 | + |
| 152 | +If you run into any problems or have questions while contributing, you're always welcome to [open an issue](https://github.com/graphql/graphql.github.io/issues/new). |
| 153 | + |
| 154 | +# Opening a PR to contribute your code |
| 155 | + |
| 156 | +You can also ping our team in the [#website channel on the GraphQL Slack](https://graphql.slack.com/messages/website/). [Get your invite here!](https://graphql-slack.herokuapp.com/) |
| 157 | + |
| 158 | +This repository is managed by EasyCLA. Project participants must sign the free ([GraphQL Specification Membership agreement](https://preview-spec-membership.graphql.org) before making a contribution. You only need to do this one time, and it can be signed by [individual contributors](http://individual-spec-membership.graphql.org/) or their [employers](http://corporate-spec-membership.graphql.org/). |
| 159 | + |
| 160 | +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. |
| 161 | + |
| 162 | +You can find [detailed information here ](https://github.com/graphql/graphql-wg/tree/main/membership). If you have issues, please email [[email protected]](mailto:[email protected]). |
| 163 | + |
| 164 | +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](https://foundation.graphql.org/join). |
0 commit comments