Skip to content

Commit 83094b8

Browse files
carolstrancarolstran
authored
Add contributing guide (#970)
* Initial commit - shiny new contributing guide * Grammar and clarity tweaks * More tweaks
1 parent 6bb2cc6 commit 83094b8

File tree

2 files changed

+133
-31
lines changed

2 files changed

+133
-31
lines changed

‎CONTRIBUTING.md

+130
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
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+
- [Contributing something else](#contributing-something-else)
24+
- [Asking questions](#asking-questions)
25+
26+
## Development guide
27+
28+
### Running the site locally
29+
30+
First, clone this repository and move into the directory:
31+
32+
```bash
33+
git clone https://github.com/graphql/graphql.github.io.git
34+
cd graphql.github.io
35+
```
36+
37+
Then, use [Yarn](https://yarnpkg.com/getting-started/install) to install and load all the necessary dependencies:
38+
39+
```bash
40+
yarn
41+
```
42+
43+
> Note: [Yarn is currently the only way to run the site locally](https://github.com/graphql/graphql.github.io/issues/946).
44+
45+
Run the `start` script to launch the server:
46+
47+
```bash
48+
yarn start
49+
```
50+
51+
Finally, open [http://localhost:8000](http://localhost:8000) to view it in the browser.
52+
53+
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.
54+
55+
### Branching
56+
57+
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`.
58+
59+
### Project structure
60+
61+
- `static`: Files that will be copied directly to `public`.
62+
- `public`: Output files that will be served by a static HTTP server.
63+
- `src`: Markdown and the TypeScript/JavaScript files used to generate the website.
64+
- `assets`: All the [`less`](http://lesscss.org/) files that contain stylesheets.
65+
- `components` and `Containers`: React components used for layouts and pages.
66+
- `content`: Markdown files with the content of pages.
67+
- `templates`: Layout templates.
68+
- `utils`: Helper functions.
69+
70+
### Publishing the updated site
71+
72+
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/).
73+
74+
## Updating content
75+
76+
### Fix a typo, code sample bug, or formatting
77+
78+
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.
79+
80+
All of the content on graphql.org is written and formatted in [Markdown](https://www.gatsbyjs.com/docs/mdx/markdown-syntax/).
81+
82+
### Add a library or tool to the Code page
83+
84+
The [Code page](https://graphql.org/code/) is a collection of libraries, tools, and services built for GraphQL.
85+
86+
To add your resource to this page, follow our [development guide](#development-guide) to [open a pull request](https://github.com/graphql/graphql.github.io/pulls).
87+
88+
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/).
89+
90+
### Add a resource to the Community page
91+
92+
The [Community page](https://graphql.org/community/) highlights resources and groups that help people get more involved with GraphQL.
93+
94+
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).
95+
96+
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/).
97+
98+
### Add a question to the FAQ
99+
100+
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.
101+
102+
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.
103+
104+
> Note: All answers in this section should be vendor-neutral and accessible to GraphQL users of all levels.
105+
106+
When your answer is ready, [open a pull request](https://github.com/graphql/graphql.github.io/pulls/).
107+
108+
### Write a new section or guide
109+
110+
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.
111+
112+
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/).
113+
114+
Once it's ready for review, please [open a pull request](https://github.com/graphql/graphql.github.io/pulls/).
115+
116+
## Making changes to the code
117+
118+
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.
119+
120+
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.
121+
122+
## Contributing something else
123+
124+
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.
125+
126+
## Asking questions
127+
128+
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).
129+
130+
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/)

‎README.md

+3-31
Original file line numberDiff line numberDiff line change
@@ -1,35 +1,7 @@
11
# Source Repository for graphql.org
2-
This repository contains the source code of https://graphql.org website.
3-
4-
# Contributing
5-
6-
Organization gh-pages deploy the `master` branch, so active development occurs
7-
on this `source` branch.
8-
9-
### Making changes
10-
11-
The first time, get all the dependencies loaded via
12-
13-
`$ npm install` or `$ yarn install`
142

15-
Then, run the server via
16-
17-
`$ npm start` or `$ yarn start`
18-
19-
Open [http://localhost:8000](http://localhost:8000) to view it in the browser.
20-
Anytime you make some changes, refresh the page to see the updates.
21-
22-
### Folder structure
23-
24-
- `static` folder contains the files that will be copied directly to `public` folder which will contain the output files to be served by a static HTTP server.
25-
26-
- `src` folder contains markdown and TypeScript/JavaScript files used to generate the website;
27-
- - `assets` folder contains `less` files and those files contain stylesheets
28-
- - `components` and `Containers` folders contains React components that are used in layouts and pages
29-
- - `content` folder contains markdown files for the content of pages
30-
- - `templates` contains the layout templates
31-
- - `utils` contains helper functions
3+
This repository contains the source code of https://graphql.org website.
324

33-
### Publish the Website
5+
## Contributing
346

35-
Once pushed to the `source` branch, CI will publish http://graphql.org
7+
Check out our [contributing guide](./CONTRIBUTING.md) for detailed instructions for how to make changes to graphql.org 🎉

0 commit comments

Comments
 (0)