Add page around PR checks to contribution guidelines. (open-telemetry…

…#4006)

content/en/docs/contributing/_index.md

@@ -369,14 +369,8 @@ using [Netlify](https://www.netlify.com/).
   the OpenTelemetry website with your changes applied. This is how reviewers
   check your changes.
 
-Other checks might also fail, including:
-
-- File name checks
-- Links resolution
-- Markdown formatting
-- Spelling
-
-GitHub also automatically assigns labels to a PR to help reviewers.
+Other checks might also fail, see the
+[list of all PR checks](/docs/contributing/pr-checks).
 
 #### Fix content issues automatically
 

content/en/docs/contributing/pr-checks.md

@@ -0,0 +1,110 @@
+---
+title: Pull request checks
+description: Learn how to make your pull request successfully pass all checks
+weight: 40
+cSpell:ignore: REFCACHE
+---
+
+When you raise a
+[pull request](https://docs.github.com/en/get-started/learning-about-github/github-glossary#pull-request)
+(PR) with the
+[opentelemetry.io repository](https://github.com/open-telemetry/opentelemetry.io)
+a set of checks are executed. The PR checks verify that...
+
+- … you have signed the [CLA](#easy-cla).
+- …your commit can be deployed through [Netlify](#netlify-deployment)
+  successfully.
+- … your changes are compliant with our [style guide](#style-checks).
+
+{{% alert title="Note" color="primary" %}}
+
+If any of the PR checks fails, please try to
+[fix content issues automatically](/docs/contributing/#fix-content-issues-automatically)
+first by running `npm run fix:all` on your machine.
+
+Additionally, you can comment `/fix:all` on your Pull Request. This will make
+the OpenTelemetry Bot run those commands on your behalf and update the PR. Make
+sure that you pull those changes locally.
+
+Only if your issues persist, read below what the different checks do and how you
+can recover from a failed state.
+
+{{% /alert %}}
+
+## Easy CLA
+
+This check fails if you haven't
+[signed the CLA](/docs/contributing/#sign-the-cla).
+
+## Netlify deployment
+
+If the [Netlify](https://www.netlify.com/) build fails, select **Details** for
+more information.
+
+## Style checks
+
+To make sure that contributions follow our
+[style guide](/docs/contributing/style-guide) we have implemented a set of
+checks that verify style guide rules and fail l if they find any issues.
+
+The following list describes current checks and what you can do to fix related
+errors:
+
+### TEXT linter
+
+This check verifies that
+[OpenTelemetry-specific terms and words are used consistently across the site](/docs/contributing/style-guide#opentelemetryio-word-list).
+
+If any issues are found, annotations are added to your files in the
+`files changed` view of your PR. Fix those to turn the check green. As an
+alternative, you can run `npm run check:text -- --fix` locally to fix most
+issues. Run `npm run check:text` again and manually fix the remaining issues.
+
+### MARKDOWN linter
+
+This check verifies that
+[standards and consistency for Markdown files are enforced](/docs/contributing/style-guide#markdown-standards).
+
+If any issues are found, run `npm:run format` to fix most issues. For more
+complex issues, run `npm run check:markdown` and apply the suggested changes.
+
+### SPELLING check
+
+This check verifies that
+[all words are spelled correctly](/docs/contributing/style-guide#spell-checking).
+
+### CSPELL:IGNORE check
+
+This check will verify that all words in your cSpell ignore list are normalized.
+
+If this check fails, run `npm run fix:dict` locally and push the changes in a
+new commit.
+
+### FILENAME check
+
+This check verifies that all
+[files are formatted by prettier](/docs/contributing/style-guide#file-format).
+
+If this check fails, run `npm fix:format` locally and push the changes in a new
+commit.
+
+### FILE FORMAT
+
+This check verifies that all
+[file names are in kebab-case](/docs/contributing/style-guide#file-names).
+
+If this check fails, run `npm fix:filenames` locally and push the changes in a
+new commit.
+
+### BUILD and CHECK LINKS / REFCACHE updates?
+
+This check verifies that all links that your commits are introducing are
+functional.
+
+Run `npm run check:links` to check them locally. This also updates the reference
+cache, or `REFCACHE`. Push any changes to the `REFCACHE` in a new commit.
+
+### WARNINGS in build log?
+
+If this check fails, review the build log for any other potential issues. Ask
+maintainers for help, if you are unsure how to recover.

content/en/docs/contributing/style-guide.md

@@ -14,6 +14,18 @@ documentation style is inspired by the following style guides:
 The following sections contain guidance that is specific to the OpenTelemetry
 project.
 
+{{% alert title="Note" color="primary" %}}
+
+Many requirements of our style guide can be enforced by running automation:
+before submitting a
+[pull request](https://docs.github.com/en/get-started/learning-about-github/github-glossary#pull-request)
+(PR), run `npm run fix:all` on your local machine and commit the changes.
+
+If you run into errors or [failed PR checks](/docs/contributing/pr-checks), read
+about our style guide below and what you can do to fix certain common issues.
+
+{{% /alert %}}
+
 ## OpenTelemetry.io word list
 
 A list of OpenTelemetry-specific terms and words to be used consistently across
@@ -37,3 +49,69 @@ file.
 
 See also the [Glossary](/docs/concepts/glossary/) for a list of OpenTelemetry
 terms and their definition.
+
+Run `npm run check:text` to verify that all terms and words are written
+properly.
+
+Run `npm run check:text -- --fix` to fix terms and words that are not written
+properly.
+
+## Markdown standards
+
+To enforce standards and consistency for Markdown files, all files should follow
+certain rules, enforced by
+[markdownlint](https://github.com/DavidAnson/markdownlint). For a full list,
+check the
+[`.markdownlint.json`](https://github.com/open-telemetry/opentelemetry.io/blob/main/.markdownlint.json)
+file.
+
+Run `npm run check:markdown` to verify that all files follow the standard.
+
+Run `npm run fix:markdown` to fix Markdown related formatting issues.
+
+## Spell checking
+
+Use [CSpell](https://github.com/streetsidesoftware/cspell) to make sure that all
+your text is spelled correctly. For a list of words that are specific to the
+OpenTelemetry website, see the
+[`.cspell.yml`](https://github.com/open-telemetry/opentelemetry.io/blob/main/.cspell.yml)
+file.
+
+Run `npm run check:spelling` to verify that all your words are spelled
+correctly. If `cspell` indicates an `Unknown word` error, verify if you wrote
+that word correctly. If so, add this word to the `cSpell:ignore` section at the
+top of your file. If no such section exists, you can add it to the front matter
+of a Markdown file:
+
+```markdown
+---
+title: PageTitle
+cSpell:ignore: <word>
+---
+```
+
+For any other file, add `cSpell:ignore <word>` in a comment line appropriate for
+the file's context. For a [registry](/ecosystem/registry/) entry YAML file file,
+it might look like this:
+
+```yaml
+# cSpell:ignore <word>
+title: registryEntryTitle
+```
+
+Website tooling normalizes page-specific dictionaries (that is, the
+`cSpell:ignore` word lists), by removing duplicate words, deleting words in the
+global word list, and sorting words. To normalize page-specific dictionaries,
+run `npm run fix:dict`.
+
+## File format
+
+To enforce a certain standard on how files are structured, all files should be
+formatted by [prettier](https://prettier.io). Run `npm fix:format` before
+submitting a PR, or run it afterwards and push an additional commit.
+
+## File names
+
+All file names should be in
+[kebab case](https://en.wikipedia.org/wiki/Letter_case#Kebab_case). Run
+`npm fix:filenames` to automatically rename your files.

static/refcache.json

@@ -1007,6 +1007,10 @@
     "StatusCode": 206,
     "LastSeen": "2024-01-30T06:05:58.662694-05:00"
   },
+  "https://docs.github.com/en/get-started/learning-about-github/github-glossary#pull-request": {
+    "StatusCode": 206,
+    "LastSeen": "2024-02-15T11:30:46.466434+01:00"
+  },
   "https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests": {
     "StatusCode": 206,
     "LastSeen": "2024-01-30T15:25:17.633498-05:00"
@@ -1731,6 +1735,10 @@
     "StatusCode": 200,
     "LastSeen": "2024-01-18T19:02:27.095072-05:00"
   },
+  "https://en.wikipedia.org/wiki/Letter_case#Kebab_case": {
+    "StatusCode": 200,
+    "LastSeen": "2024-02-15T11:30:50.951761+01:00"
+  },
   "https://en.wikipedia.org/wiki/Log_file": {
     "StatusCode": 200,
     "LastSeen": "2024-01-18T19:01:58.409935-05:00"
@@ -2003,6 +2011,10 @@
     "StatusCode": 200,
     "LastSeen": "2024-01-18T19:10:56.414699-05:00"
   },
+  "https://github.com/DavidAnson/markdownlint": {
+    "StatusCode": 200,
+    "LastSeen": "2024-02-15T11:30:50.043802+01:00"
+  },
   "https://github.com/DebajitDas": {
     "StatusCode": 200,
     "LastSeen": "2024-01-18T20:04:53.923765-05:00"
@@ -4087,6 +4099,10 @@
     "StatusCode": 200,
     "LastSeen": "2024-01-18T19:12:56.889858-05:00"
   },
+  "https://github.com/streetsidesoftware/cspell": {
+    "StatusCode": 200,
+    "LastSeen": "2024-02-15T11:30:50.628118+01:00"
+  },
   "https://github.com/strimzi": {
     "StatusCode": 200,
     "LastSeen": "2024-01-18T20:05:40.859417-05:00"
@@ -6555,6 +6571,10 @@
     "StatusCode": 206,
     "LastSeen": "2024-01-30T16:05:44.189442-05:00"
   },
+  "https://prettier.io": {
+    "StatusCode": 206,
+    "LastSeen": "2024-02-15T11:32:15.231585+01:00"
+  },
   "https://projectreactor.io/docs/core/release/api/reactor/core/publisher/Flux.html": {
     "StatusCode": 200,
     "LastSeen": "2024-01-18T19:10:54.695167-05:00"