graphql-engine/docs/wiki/contributions.mdx

---
sidebar_label: Contributing to Docs
sidebar_position: 30
---

import Thumbnail from '@site/src/components/Thumbnail';
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Contributing to Docs

## Overview

Docs contributions take many forms. However, they all follow the same workflow. Below, you'll find all you need to get
your local development environment set up and - before you know it - you'll be helping make our product clearer for
users.

## Mise-en-place

Like
[Uncle Tony](https://i0.wp.com/jamesabrock.com/wp-content/uploads/2018/06/IMG_0013-1024x682.jpg?fit=676%2C450&ssl=1)
said:

> “Mise-en-place is the religion of all good line cooks...”

Docs believes the same is true for engineers and all contributors to documentation.

As such, there's a few steps needed to get your 'station' in order and to ready your local development environment for
the fast-paced world of documentation.

We use Yarn as our package-manager- / project-manager-of-choice. Please make sure you follow
[their installation instructions](https://yarnpkg.com/getting-started/install) if not already on your system.

Two `hasura/graphql-engine` repositories exist: one is our OSS repo whereas the other is a private repository only
available to employees at Hasura. We utilize these two repos so we can maintain open-source contributions and also
provide an undisturbed repository to which the community has access. As changes are merged into our private repository,
they're reflected in the OSS version as well.

Anywhere where there are differences in procedure between community contributions and those of Hasurians, tabs can be
found. If you're a member of the community looking to contribute to docs, follow the **Community Member** instructions
inside each step. Alternatively, Hasurians should follow the instructions which fall under their tab.

:::info Note

Like to automate things? So do we. This snippet runs through the prerequisites for Hasurians and fires up the docs
development server. Simply navigate to the directory you want the `hasura-graphql-engine-mono` repo to live, open your
terminal, copy / paste, hit enter, and save literally seconds:

```bash
git clone https://github.com/hasura/graphql-engine-mono.git
cd graphql-engine-mono/docs
yarn install
yarn start
```

:::

Alternatively, take it step-by-step:

### Step 1: Clone the repository

<Tabs>
<TabItem value='hasurians' label='Hasurians'>

```bash
git clone https://github.com/hasura/graphql-engine-mono.git
```

</TabItem>
<TabItem value='community' label='Community Members'>

If you're a community member, you'll first need to fork the `hasura/graphql-engine` repository. If logged into GitHub,
you can do that by [simply pressing](https://github.com/hasura/graphql-engine/fork) here.

Once you have your own forked copy of the `graphql-engine` repo, you can clone **this** to your machine. Simply replace
`<your-github-username>` with your information:

```bash
git clone https://github.com/<your-github-username>/graphql-engine.git
```

</TabItem>
</Tabs>

### Step 2: Install docs dependencies

<Tabs>
<TabItem value='hasurians' label='Hasurians'>

```bash
cd graphql-engine-mono/docs && yarn install
```

</TabItem>
<TabItem value='community' label='Community Members'>

```bash
cd graphql-engine/docs && yarn install
```

</TabItem>
</Tabs>

We also highly recommend testing locally at this point. Start the development server by running the following command:

```bash
yarn start
```

If the server doesn't start, check the errors logging to the terminal. You can also check the
[common errors section](#common-errors) at the bottom of this page. Hit up Sean Park-Ross on
[Slack](https://hasurahq.slack.com/team/U03J31UJ8V7) (for Hasurians) or
[Discord](https://discord.com/users/981277708564721694) (for our community members) / Rob Dominguez on
[Slack](https://hasurahq.slack.com/team/U03H7ABDMF1) (for Hasurians) or [Discord](https://discord.com/users/5592) (for
our community members) if you need help troubleshooting.

Otherwise, congrats! You're ready to start slinging docs 🤙

## Workflow

### Step 1: Create a new branch

If it's been a while since you've pulled from `main` (`master` for the OSS repo), make sure it's up-to-date before
creating a new branch for this contribution. You can simply run `git pull` while on the trunk to update your local
repository to the current state of the remote on GitHub. Then, utilize the command below the next paragraph to create
your branch.

If this is a fresh clone, there shouldn't be any need to `pull` changes down from GitHub. You can create a new branch
and simultaneously switch to it using the command below. We follow a convention that includes your name + `docs` + a
kebab-cased description of what the branch will focus on. For example: `rob/docs/add-more-bourdain-references`.

```bash
git checkout -b <your-name>/docs/<short-update-description>
```

Once this command is run, you should be on your new branch!

### Step 2: Start the development server

You'll want to start the development server so you can see all your changes live. Especially the first time, the
development server will take _some_ time to spin up. However, Docusaurus caches content...so this gets better with
repetition.

```bash
yarn start
```

### Step 3: Make your local changes

We have a [comprehensive-yet-continually-evolving style guide](/wiki/category/style/). We ask that you reference it as
you begin formatting your docs contribution.

If you don't want to go piece-by-piece in the style guide, find a page of documentation you think works well and use it
as a template.

:::info Note

Docusaurus utilizes a file-based routing system. You can see more about
[working with Docusaurus](/working-with-docusaurus.mdx) here.

Most files you'll be authoring will be `.mdx`. It's like markdown on steroids and allows utilization of `jsx`
components. For more information about the syntax of markdown,
[check out these docs](https://www.markdownguide.org/basic-syntax/).

:::

### Step 4: Stage your local changes

After your changes have been made, you'll need to stage them using Git. The following command will add all modifications
you've made to Git's staging area:

```bash
git add .
```

### Step 5: Create a commit

With your changes staged, you'll need to create a commit with a commit message. Prefix the message with `docs:` and a
imperative verb followed by a description of the changes present in the commit:

```bash
git commit -m “docs: update / fix / add <feature>”
```

:::info Note

The size of commits isn't of massive importance for docs contributions. If you're here for a quick fix, chances are
there will only be one commit. Alternatively, if you're working on a large contribution documenting a new feature and
need to modify / add / delete multiple files, it helps to have more atomic commits reflective of each set of actions.

:::

### Step 6: Test your local changes

We don't have unit tests for docs. However, Docusaurus will (generally) let you know when it's not happy with something
you did. As such, our testing process consists of doing a build and serving from the `build` folder to make sure
everything functions correctly. To start your build, from the `/docs` directory, run:

```bash
yarn build
```

After a bit, you should see output similar to this:

```bash
# Lots of other output above this...
[SUCCESS] Generated static files in build.
[INFO] Use `npm run serve` command to test your build locally.
✨  Done in 35.84s.
```

If you don't see an output similar to the above (especially one that's missing `SUCCESS`), something went wrong. There
should be errors logged in the terminal; check the [common errors section](#common-errors) at the bottom of this page
for more info.

Once you achieve a successful build, serve the `build` folder using the following command:

```bash
yarn serve
```

All you're doing here is checking to ensure your pages render as expected. Go through any changes you made and ensure
there's no missing images, broken links, or malformations in your code snippets (especially `gql`!).

### Step 7: Push your commit(s)

With everything rendering as expected, it's time to push this contribution online! Run the following to push your
changes up to GitHub:

```bash
git push origin <name-of-your-branch>
```

### Step 8: Compare and pull request

<Tabs>
<TabItem value='hasurians' label='Hasurians'>

Head to the `hasura/graphql-engine-mono` repo and you should see a `Compare & pull request` button - click it to create
you PR 🤙

Follow the instructions in the PR template and don't forget to add the `c/docs` label.

Once you open your PR, hasura-bot will assign a docs reviewer, and prompt you with some steps you need to complete for us to review your PR. You'll also get a handy preview link (which will need some time to build) at the end of the comment.

</TabItem>
<TabItem value='community' label='Community Members'>

Head to your forked copy of the `hasura/graphql-engine` repo and you should see a `Compare & pull request` button -
click it to create you PR 🤙

Follow the instructions in the PR template and don't forget to add the `c/docs` label.

We'll get a ping from hasura-bot and review your great work ASAP 🔥

</TabItem>
</Tabs>

:::info Note

If you're including a significant feature update or bug fix that should be noted on the next release, please be sure to
update `CHANGELOG.md` in the root directory of the repo as well.

:::

## Common errors

We all make mistakes! Here's the most common ones we encounter. This is not an exhaustive list, but if you find lots of
errors getting thrown, chances are the issue is one of the items below. These are rank-ordered according to what we
encounter most often.

### Broken markdown links

With Docusaurus's file-based routing system, markdown links commonly break due to one of two circumstances:

- Filename changes

  The url path for a particular page is dependent upon its filename. If you change the name of a file, any link
  referencing it will break. The error thrown to the Console will alert you to which page contains the error and to
  which file is being referenced. If there are multiple broken links, it will list out each.

- File location changes

  If you change the name of a file or folder (e.g., `modelling/index.mdx` to `modeling/index.mdx`), any links
  referencing this route will break. Often, simply resolving these paths isn't enough...Docusaurus will still be looking
  for these files. If this is the case, kill the server (`CTRL+c`) and start it up again by running `yarn start`.

Regardless of which of the above circumstances caused this error, you'll see output similar to this within the server
console:

```bash
Error: Docs markdown link couldn't be resolved: (/styles/index.mdx) in ~/hasura/graphql-engine-mono/docs/wiki/contributions.mdx for version current
    at Array.forEach (<anonymous>)
client (webpack 5.70.0) compiled with 1 error
```

### Broken image links

Assets are stored in `static/img/<feature-folder>`. Just like the file-based routing Docusaurus uses to render pages,
file paths are important for images as well. However, instead of any output to the Console, the page will simply crash
and present a message indicating which image's path cannot be resolved.

<Thumbnail
  src="/img/wiki/broken-image.png"
  alt="Add check constraint"
  width="1000px"
/>

Use the erroneous image path to identify the error, facepalm, and then fix your typo.

:::info Note

We use the PNG image format. When you create a PR, our automated CI processes take care of image optimization
automatically 🚀

:::

### Improperly imported components

This is a sneaky one. If you forget to import a component - such as the `<Thumbnail />` component used for images -
there won't be any errors thrown by the server. However, if you check your browser's developer tools, you'll notice the
quite prominent error. Thus, when something just isn't appearing...check the browser's Console.

Simply import the missing component at the top of the page and viola 🤌

### Formatting code blocks

Perhaps the biggest pitfall we've encountered with Docusaurus is how delicate `.mdx` files can be with regard to
placement of code blocks and other text. If you've included a code block using common markdown syntax, and things aren't
rendering as you think they should, try giving the block a bit of breathing room with a single empty line above and
below it.

## Codespaces

:::info Note

For Hasurians, we've recently introduced a new way to contribute to the docs:
[Codespaces](https://docs.github.com/en/codespaces). This is a new feature from GitHub that allows you to spin up a
fully-configured docs dev environment in the cloud. This means you can get started contributing to the docs without
having to install any dependencies on your local machine.

:::

### Step 1: Create a Codespace

Head to the `hasura/graphql-engine-mono` repo and click the `Code` button. You should see a `Open with Codespaces`
button. Click it and choose `...` and then `+ New with options...` as in the example below:

<Thumbnail
  src="/img/wiki/codespaces-1.gif"
  alt="Create Codespace"
  width="1000px"
/>

### Step 2: Configure your Codespace

You'll be presented with a few options. Select the `docs` devcontainer, the region nearest to you, and a machine type
before clicking `Create codespace`:

<Thumbnail
  src="/img/wiki/codespaces-2.gif"
  alt="Create Codespace"
  width="1000px"
/>

The Codespace will spin up and you'll be presented with a fully-configured dev environment. We automatically open you to
the `CODESPACES.md` file where you can follow the instructions to get started quickly.