mirror of
https://github.com/hasura/graphql-engine.git
synced 2024-12-15 09:22:43 +03:00
9c48313f81
PR-URL: https://github.com/hasura/graphql-engine-mono/pull/6240 GitOrigin-RevId: 406303a03e5258c20baa5c49f52be8d6262a7535
58 lines
2.8 KiB
Plaintext
58 lines
2.8 KiB
Plaintext
---
|
|
sidebar_label: PR Review Checklist
|
|
sidebar_position: 40
|
|
---
|
|
|
|
# PR Checklist
|
|
|
|
Everybody is different, and we all review PRs in our way. However, there are some common elements we examine and
|
|
questions we ask ourselves when reviewing a PR. Our goal in providing this document is to give you a "docs-reviewer"
|
|
lens through which to look. In the long run, taking a quick parse through your contribution while thinking about these
|
|
steps and questions will ensure we can approve your docs changes and merge your PR swiftly. **We hold a strict standard
|
|
because we want to ensure our users can quickly find what they need, understand it because it's well-written, and get
|
|
back to building with Hasura** 🚀
|
|
|
|
## Pass one: grammar school
|
|
|
|
As we're reading through a PR for the first time and trying to gather context, most of us focus on easy wins. While
|
|
we're formulating a structure and trying to get a better idea of the document you've created, we're also trying to pick
|
|
out quick typos like the following:
|
|
|
|
- Misspelled words
|
|
- Missing punctuation
|
|
- Extra or missing whitespaces
|
|
- Sentence structure / syntax
|
|
|
|
When we see these, we'll generally offer suggestions you can commit directly from GitHub. However, we should note that
|
|
reviews filled with errors like these take longer to review (and are less fun).
|
|
|
|
:::info Note
|
|
|
|
We hope to introduce a simple linter that examines spelling as part of our CI pipeline on any PRs that include docs
|
|
contributions.
|
|
|
|
:::
|
|
|
|
## Pass two: infrastructure
|
|
|
|
Next, we'll typically do an infrastructure test (i.e., does everything 'work'?). If you followed the guidelines in our
|
|
[style guide](/wiki/category/style/), you're probably okay. However, we'll also do the following:
|
|
|
|
- Check new internal links and ensure they're
|
|
[root-relative file paths](/docusaurus-mdx-guide/page-structure.mdx#references--links)
|
|
- Check external links and ensure they're not returning `404`
|
|
- Double-check headings are [correctly cased](/style/headings.mdx)
|
|
- Look for Hasura features (like Hasura Console, Metadata, Migrations) and ensure they're proper cases
|
|
- Look for opportunities to cross-link to other pages in docs
|
|
|
|
## Pass three: structural integrity
|
|
|
|
Finally, we can focus on the total product: the docs themselves. We ask ourselves a few questions as we're judging the
|
|
contribution (yes, we're judgy and, in fact, judged everything you wrote and probably have strong opinions at this point
|
|
😅). The central theme around which we target all these questions is UX:
|
|
|
|
- How will a user interpret this new section / page?
|
|
- If a user starts at the beginning of the page, will they understand the new contribution?
|
|
- If a user arrives from another page, and the new contribution is a nested section of an existing page, will they have
|
|
enough context to understand the value of the contribution?
|