--- 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 ```bash git clone https://github.com/hasura/graphql-engine-mono.git ``` 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 `` with your information: ```bash git clone https://github.com//graphql-engine.git ``` ### Step 2: Install docs dependencies ```bash cd graphql-engine-mono/docs && yarn install ``` ```bash cd graphql-engine/docs && yarn install ``` 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 /docs/ ``` 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 ” ``` :::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 ``` ### Step 8: Compare and pull request 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. 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 πŸ”₯ :::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 () client (webpack 5.70.0) compiled with 1 error ``` ### Broken image links Assets are stored in `static/img/`. 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. 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 `` 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: ### 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`: 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.