Skip to content

Commit 309d458

Browse files
svrnmsvrnm
authored
Add page around PR checks to contribution guidelines. (open-telemetry#4006)
1 parent 8a967b7 commit 309d458

File tree

4 files changed

+210
-8
lines changed

4 files changed

+210
-8
lines changed

‎content/en/docs/contributing/_index.md

+2-8
Original file line numberDiff line numberDiff line change
@@ -369,14 +369,8 @@ using [Netlify](https://www.netlify.com/).
369369
the OpenTelemetry website with your changes applied. This is how reviewers
370370
check your changes.
371371

372-
Other checks might also fail, including:
373-
374-
- File name checks
375-
- Links resolution
376-
- Markdown formatting
377-
- Spelling
378-
379-
GitHub also automatically assigns labels to a PR to help reviewers.
372+
Other checks might also fail, see the
373+
[list of all PR checks](/docs/contributing/pr-checks).
380374

381375
#### Fix content issues automatically
382376

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

+110
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
---
2+
title: Pull request checks
3+
description: Learn how to make your pull request successfully pass all checks
4+
weight: 40
5+
cSpell:ignore: REFCACHE
6+
---
7+
8+
When you raise a
9+
[pull request](https://docs.github.com/en/get-started/learning-about-github/github-glossary#pull-request)
10+
(PR) with the
11+
[opentelemetry.io repository](https://github.com/open-telemetry/opentelemetry.io)
12+
a set of checks are executed. The PR checks verify that...
13+
14+
- … you have signed the [CLA](#easy-cla).
15+
- …your commit can be deployed through [Netlify](#netlify-deployment)
16+
successfully.
17+
- … your changes are compliant with our [style guide](#style-checks).
18+
19+
{{% alert title="Note" color="primary" %}}
20+
21+
If any of the PR checks fails, please try to
22+
[fix content issues automatically](/docs/contributing/#fix-content-issues-automatically)
23+
first by running `npm run fix:all` on your machine.
24+
25+
Additionally, you can comment `/fix:all` on your Pull Request. This will make
26+
the OpenTelemetry Bot run those commands on your behalf and update the PR. Make
27+
sure that you pull those changes locally.
28+
29+
Only if your issues persist, read below what the different checks do and how you
30+
can recover from a failed state.
31+
32+
{{% /alert %}}
33+
34+
## Easy CLA
35+
36+
This check fails if you haven't
37+
[signed the CLA](/docs/contributing/#sign-the-cla).
38+
39+
## Netlify deployment
40+
41+
If the [Netlify](https://www.netlify.com/) build fails, select **Details** for
42+
more information.
43+
44+
## Style checks
45+
46+
To make sure that contributions follow our
47+
[style guide](/docs/contributing/style-guide) we have implemented a set of
48+
checks that verify style guide rules and fail l if they find any issues.
49+
50+
The following list describes current checks and what you can do to fix related
51+
errors:
52+
53+
### TEXT linter
54+
55+
This check verifies that
56+
[OpenTelemetry-specific terms and words are used consistently across the site](/docs/contributing/style-guide#opentelemetryio-word-list).
57+
58+
If any issues are found, annotations are added to your files in the
59+
`files changed` view of your PR. Fix those to turn the check green. As an
60+
alternative, you can run `npm run check:text -- --fix` locally to fix most
61+
issues. Run `npm run check:text` again and manually fix the remaining issues.
62+
63+
### MARKDOWN linter
64+
65+
This check verifies that
66+
[standards and consistency for Markdown files are enforced](/docs/contributing/style-guide#markdown-standards).
67+
68+
If any issues are found, run `npm:run format` to fix most issues. For more
69+
complex issues, run `npm run check:markdown` and apply the suggested changes.
70+
71+
### SPELLING check
72+
73+
This check verifies that
74+
[all words are spelled correctly](/docs/contributing/style-guide#spell-checking).
75+
76+
### CSPELL:IGNORE check
77+
78+
This check will verify that all words in your cSpell ignore list are normalized.
79+
80+
If this check fails, run `npm run fix:dict` locally and push the changes in a
81+
new commit.
82+
83+
### FILENAME check
84+
85+
This check verifies that all
86+
[files are formatted by prettier](/docs/contributing/style-guide#file-format).
87+
88+
If this check fails, run `npm fix:format` locally and push the changes in a new
89+
commit.
90+
91+
### FILE FORMAT
92+
93+
This check verifies that all
94+
[file names are in kebab-case](/docs/contributing/style-guide#file-names).
95+
96+
If this check fails, run `npm fix:filenames` locally and push the changes in a
97+
new commit.
98+
99+
### BUILD and CHECK LINKS / REFCACHE updates?
100+
101+
This check verifies that all links that your commits are introducing are
102+
functional.
103+
104+
Run `npm run check:links` to check them locally. This also updates the reference
105+
cache, or `REFCACHE`. Push any changes to the `REFCACHE` in a new commit.
106+
107+
### WARNINGS in build log?
108+
109+
If this check fails, review the build log for any other potential issues. Ask
110+
maintainers for help, if you are unsure how to recover.

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

+78
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,18 @@ documentation style is inspired by the following style guides:
1414
The following sections contain guidance that is specific to the OpenTelemetry
1515
project.
1616

17+
{{% alert title="Note" color="primary" %}}
18+
19+
Many requirements of our style guide can be enforced by running automation:
20+
before submitting a
21+
[pull request](https://docs.github.com/en/get-started/learning-about-github/github-glossary#pull-request)
22+
(PR), run `npm run fix:all` on your local machine and commit the changes.
23+
24+
If you run into errors or [failed PR checks](/docs/contributing/pr-checks), read
25+
about our style guide below and what you can do to fix certain common issues.
26+
27+
{{% /alert %}}
28+
1729
## OpenTelemetry.io word list
1830

1931
A list of OpenTelemetry-specific terms and words to be used consistently across
@@ -37,3 +49,69 @@ file.
3749

3850
See also the [Glossary](/docs/concepts/glossary/) for a list of OpenTelemetry
3951
terms and their definition.
52+
53+
Run `npm run check:text` to verify that all terms and words are written
54+
properly.
55+
56+
Run `npm run check:text -- --fix` to fix terms and words that are not written
57+
properly.
58+
59+
## Markdown standards
60+
61+
To enforce standards and consistency for Markdown files, all files should follow
62+
certain rules, enforced by
63+
[markdownlint](https://github.com/DavidAnson/markdownlint). For a full list,
64+
check the
65+
[`.markdownlint.json`](https://github.com/open-telemetry/opentelemetry.io/blob/main/.markdownlint.json)
66+
file.
67+
68+
Run `npm run check:markdown` to verify that all files follow the standard.
69+
70+
Run `npm run fix:markdown` to fix Markdown related formatting issues.
71+
72+
## Spell checking
73+
74+
Use [CSpell](https://github.com/streetsidesoftware/cspell) to make sure that all
75+
your text is spelled correctly. For a list of words that are specific to the
76+
OpenTelemetry website, see the
77+
[`.cspell.yml`](https://github.com/open-telemetry/opentelemetry.io/blob/main/.cspell.yml)
78+
file.
79+
80+
Run `npm run check:spelling` to verify that all your words are spelled
81+
correctly. If `cspell` indicates an `Unknown word` error, verify if you wrote
82+
that word correctly. If so, add this word to the `cSpell:ignore` section at the
83+
top of your file. If no such section exists, you can add it to the front matter
84+
of a Markdown file:
85+
86+
```markdown
87+
---
88+
title: PageTitle
89+
cSpell:ignore: <word>
90+
---
91+
```
92+
93+
For any other file, add `cSpell:ignore <word>` in a comment line appropriate for
94+
the file's context. For a [registry](/ecosystem/registry/) entry YAML file file,
95+
it might look like this:
96+
97+
```yaml
98+
# cSpell:ignore <word>
99+
title: registryEntryTitle
100+
```
101+
102+
Website tooling normalizes page-specific dictionaries (that is, the
103+
`cSpell:ignore` word lists), by removing duplicate words, deleting words in the
104+
global word list, and sorting words. To normalize page-specific dictionaries,
105+
run `npm run fix:dict`.
106+
107+
## File format
108+
109+
To enforce a certain standard on how files are structured, all files should be
110+
formatted by [prettier](https://prettier.io). Run `npm fix:format` before
111+
submitting a PR, or run it afterwards and push an additional commit.
112+
113+
## File names
114+
115+
All file names should be in
116+
[kebab case](https://en.wikipedia.org/wiki/Letter_case#Kebab_case). Run
117+
`npm fix:filenames` to automatically rename your files.

‎static/refcache.json

+20
Original file line numberDiff line numberDiff line change
@@ -1007,6 +1007,10 @@
10071007
"StatusCode": 206,
10081008
"LastSeen": "2024-01-30T06:05:58.662694-05:00"
10091009
},
1010+
"https://docs.github.com/en/get-started/learning-about-github/github-glossary#pull-request": {
1011+
"StatusCode": 206,
1012+
"LastSeen": "2024-02-15T11:30:46.466434+01:00"
1013+
},
10101014
"https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests": {
10111015
"StatusCode": 206,
10121016
"LastSeen": "2024-01-30T15:25:17.633498-05:00"
@@ -1731,6 +1735,10 @@
17311735
"StatusCode": 200,
17321736
"LastSeen": "2024-01-18T19:02:27.095072-05:00"
17331737
},
1738+
"https://en.wikipedia.org/wiki/Letter_case#Kebab_case": {
1739+
"StatusCode": 200,
1740+
"LastSeen": "2024-02-15T11:30:50.951761+01:00"
1741+
},
17341742
"https://en.wikipedia.org/wiki/Log_file": {
17351743
"StatusCode": 200,
17361744
"LastSeen": "2024-01-18T19:01:58.409935-05:00"
@@ -2003,6 +2011,10 @@
20032011
"StatusCode": 200,
20042012
"LastSeen": "2024-01-18T19:10:56.414699-05:00"
20052013
},
2014+
"https://github.com/DavidAnson/markdownlint": {
2015+
"StatusCode": 200,
2016+
"LastSeen": "2024-02-15T11:30:50.043802+01:00"
2017+
},
20062018
"https://github.com/DebajitDas": {
20072019
"StatusCode": 200,
20082020
"LastSeen": "2024-01-18T20:04:53.923765-05:00"
@@ -4087,6 +4099,10 @@
40874099
"StatusCode": 200,
40884100
"LastSeen": "2024-01-18T19:12:56.889858-05:00"
40894101
},
4102+
"https://github.com/streetsidesoftware/cspell": {
4103+
"StatusCode": 200,
4104+
"LastSeen": "2024-02-15T11:30:50.628118+01:00"
4105+
},
40904106
"https://github.com/strimzi": {
40914107
"StatusCode": 200,
40924108
"LastSeen": "2024-01-18T20:05:40.859417-05:00"
@@ -6555,6 +6571,10 @@
65556571
"StatusCode": 206,
65566572
"LastSeen": "2024-01-30T16:05:44.189442-05:00"
65576573
},
6574+
"https://prettier.io": {
6575+
"StatusCode": 206,
6576+
"LastSeen": "2024-02-15T11:32:15.231585+01:00"
6577+
},
65586578
"https://projectreactor.io/docs/core/release/api/reactor/core/publisher/Flux.html": {
65596579
"StatusCode": 200,
65606580
"LastSeen": "2024-01-18T19:10:54.695167-05:00"

0 commit comments

Comments
 (0)