-
Notifications
You must be signed in to change notification settings - Fork 126
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: add spell-checker to contributing docs (#2504)
Signed-off-by: Meg McRoberts <[email protected]> Signed-off-by: odubajDT <[email protected]> Co-authored-by: Moritz Wiesinger <[email protected]> Co-authored-by: odubajDT <[email protected]>
- Loading branch information
1 parent
8e52eda
commit d2c6f85
Showing
3 changed files
with
157 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,76 @@ | ||
# Spell Checker | ||
|
||
All PRs that are pushed to a Keptn repository | ||
are run through a spell checker that is based on the | ||
[check-spelling](https://github.com/check-spelling/check-spelling) | ||
GitHub action. | ||
|
||
Note, however, that you are still responsible for reading your text carefully. | ||
The tool does not flag if you used a real word that is not the right word, | ||
if you misuse "setup" versus "set up", and so forth. | ||
|
||
## Handling Spell Checker errors | ||
|
||
If you get a Spell Checker error: | ||
|
||
1. Click the `details` link for Spell Checker | ||
in the checks for your PR. | ||
1. Click on the Summary to get to the job summary. | ||
1. This shows the word(s) that caused Spell Checker to fail. | ||
|
||
- If these are genuine misspellings, | ||
correct the spelling in your local branch | ||
or using the GitHub editor | ||
and push the new commit to resolve the errors. | ||
|
||
- If a word that is flagged is a legitimate word, | ||
follow the instructions in the report | ||
to propose adding it to our [dictionary](https://github.com/keptn/lifecycle-toolkit/blob/main/.github/actions/spelling/expect.txt). | ||
This request will be added to your PR for review | ||
and, if approved, will be merged when the PR is merged. | ||
|
||
- If your PR includes a file that should not be spell-checked, | ||
you can add it to the | ||
[excludes.txt](https://github.com/keptn/lifecycle-toolkit/blob/main/.github/actions/spelling/excludes.txt) file | ||
as part of your PR. | ||
It will be reviewed and, if approved, | ||
merged as part of your PR. | ||
|
||
For more details about handling errors that are found, see the | ||
[Check-spelling docs](https://docs.check-spelling.dev/). | ||
|
||
## Implementation details | ||
|
||
For full technical details about the spell checker, see: | ||
|
||
- [check-spelling documentation](https://docs.check-spelling.dev/) | ||
- [check-spelling GitHub repository](https://github.com/check-spelling/check-spelling) | ||
|
||
The Keptn spell checker checks both documentation and code for spelling, | ||
based on a set of dictionaries: | ||
|
||
- We use general English language and technical terminology | ||
from dictionaries that are provided and maintained by check-spelling. | ||
The configuration is specified in files in the | ||
[.github/actions/spelling](https://github.com/keptn/lifecycle-toolkit/tree/main/.github/actions/spelling) | ||
directory. | ||
[expect.txt](https://github.com/keptn/lifecycle-toolkit/tree/main/.github/actions/spelling/expect.txt) | ||
lists Keptn terms for both documentation and code. | ||
- We also use the specialized technical dictionaries provided by check-spelling specific domains | ||
or programming languages such as Kubernetes, Go or HTML. | ||
The dictionaries we use are specified in the | ||
[.github/workflows/spell-checker.yml](https://github.com/keptn/lifecycle-toolkit/blob/main/.github/workflows/spell-checker.yml) | ||
file. | ||
|
||
Check-spelling supports both American and British spelling | ||
and both are allowed in the Keptn documentation. | ||
|
||
Check-spelling provides dictionaries for a number of non-English languages | ||
but we do not currently use those. | ||
|
||
Note that Check-spelling does not check for proper capitalization of terms. | ||
All dictionary terms are listed with lowercase letters. | ||
Check-spelling recognizes capitalized versions of these words but, | ||
if capitalized words are listed in a dictionary, | ||
check-spelling rejects non-capitalized forms | ||
which are common in code. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,80 @@ | ||
--- | ||
title: Spell checker | ||
description: How to work with the spell checker | ||
weight: 375 | ||
--- | ||
|
||
All PRs that are pushed to a Keptn repository | ||
are run through a spell checker that is based on the | ||
[check-spelling](https://github.com/check-spelling/check-spelling) | ||
GitHub action. | ||
|
||
Note, however, that you are still responsible for reading your text carefully. | ||
The tool does not flag if you used a real word that is not the right word, | ||
if you misuse "setup" versus "set up", and so forth. | ||
|
||
## Handling Spell Checker errors | ||
|
||
If you get a Spell Checker error: | ||
|
||
1. Right-click the `details` link for Spell Checker. | ||
1. If you do not want to read through the whole (and rather verbose) log, | ||
type `unrecognized words` in the search box at the top. | ||
1. This shows the word(s) that caused Spell Checker to fail. | ||
|
||
- If these are genuine misspellings, | ||
correct the spelling in your local branch | ||
or using the github editor | ||
and push the new commit to resolve the errors. | ||
|
||
- If a word that is flagged is a legitimate word, | ||
follow the instructions in the report | ||
to propose adding it to our dictionary. | ||
This request will be added to your PR for review | ||
and, if approved, will be merged when the PR is merged. | ||
|
||
- If your PR includes a file that should not be spell-checked, | ||
you can add it to the | ||
[excludes.txt](https://github.com/keptn/lifecycle-toolkit/blob/main/.github/actions/spelling/excludes.txt) file | ||
as part of your PR. | ||
It will be reviewed and, if approved, | ||
merged as part of your PR. | ||
|
||
For more details about handling errors that are found, see the | ||
[Check-spelling docs](https://docs.check-spelling.dev/). | ||
|
||
## Implementation details | ||
|
||
For full technical details about the spell checker, see: | ||
|
||
- [check-spelling documentation](https://docs.check-spelling.dev/) | ||
- [check-spelling GitHub repository](https://github.com/check-spelling/check-spelling) | ||
|
||
The Keptn spell checker checks both documentation and code for spelling, | ||
based on a set of dictionaries: | ||
|
||
- We use general English language and technical terminology | ||
from dictionaries that are provided and maintained by check-spelling. | ||
The configuration is specified in files in the | ||
[.github/actions/spelling](https://github.com/keptn/lifecycle-toolkit/tree/main/.github/actions/spelling) | ||
directory. | ||
[expect.txt](https://github.com/keptn/lifecycle-toolkit/tree/main/.github/actions/spelling/expect.txt) | ||
lists Keptn terms for both documentation and code. | ||
- We also use the specialized technical dictionaries provided by check-spelling | ||
for Kubernetes and Go. | ||
The dictionaries we use are specified in the | ||
[.github/workflows/spell-checker.yml](https://github.com/keptn/lifecycle-toolkit/blob/main/.github/workflows/spell-checker.yml) | ||
file. | ||
|
||
Check-spelling supports both American and British spelling | ||
and both are allowed in the Keptn documentation. | ||
|
||
Check-spelling provides dictionaries for a number of non-English languages | ||
but we do not currently use those. | ||
|
||
Note that Check-spelling does not check for proper capitalization of terms. | ||
All dictionary terms are listed with lowercase letters. | ||
Check-spelling recognizes capitalized versions of these words but, | ||
if capitalized words are listed in a dictionary, | ||
check-spelling rejects non-capitalized forms | ||
which are common in code. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters