Skip to content

Commit 52ffd83

Browse files
lgallardlgallard
committed
docs: fix spell-check documentation to avoid false positives
- Updated SPELL_CHECK.md to reference typos.toml instead of listing examples - Prevents typos tool from flagging deliberate misspelling examples - Maintains comprehensive documentation while avoiding conflicts
1 parent 87a389e commit 52ffd83

File tree

4 files changed

+238
-3
lines changed

4 files changed

+238
-3
lines changed

‎.github/SPELL_CHECK.md‎

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
# Spell Check Guide
2+
3+
## Overview
4+
5+
This repository uses automated spell-checking to maintain high documentation quality across all markdown files and text content.
6+
7+
## Tools & Configuration
8+
9+
### Primary Tool: Typos
10+
- **Tool**: [crate-ci/typos](https://github.com/crate-ci/typos)
11+
- **Configuration**: `typos.toml`
12+
- **Integration**: Pre-commit hook
13+
14+
### Configuration File: typos.toml
15+
16+
The `typos.toml` file contains:
17+
- **Company names**: HashiCorp, etc.
18+
- **Common misspellings**: See typos.toml for full list
19+
- **Technical terms**: AWS, Terraform, backup-specific vocabulary
20+
- **Infrastructure terms**: resource, configuration, environment, etc.
21+
22+
## Pre-commit Integration
23+
24+
Spell-checking runs automatically via pre-commit hooks:
25+
26+
```yaml
27+
- repo: https://github.com/crate-ci/typos
28+
rev: v1.16.23
29+
hooks:
30+
- id: typos
31+
types: [markdown, text]
32+
args: ['--format', 'long', '--config', 'typos.toml']
33+
exclude: '^test_.*\.md$|.*test_formatting.*'
34+
```
35+
36+
## Running Spell Check Manually
37+
38+
### Check all files:
39+
```bash
40+
pre-commit run typos --all-files
41+
```
42+
43+
### Check specific file:
44+
```bash
45+
pre-commit run typos --files README.md
46+
```
47+
48+
### Check all markdown files:
49+
```bash
50+
pre-commit run typos --files $(find . -name "*.md")
51+
```
52+
53+
## Adding New Words
54+
55+
### For legitimate words flagged as typos:
56+
57+
1. Edit `typos.toml`:
58+
```toml
59+
[default.extend-words]
60+
YourWord = "YourWord"
61+
```
62+
63+
2. Test the configuration:
64+
```bash
65+
pre-commit run typos --all-files
66+
```
67+
68+
### For actual misspellings to fix:
69+
70+
1. Add the correction to `typos.toml`:
71+
```toml
72+
[default.extend-words]
73+
misspelling = "misspelling"
74+
```
75+
76+
2. This allows the word in existing content while encouraging correct spelling in new content.
77+
78+
## Common Misspellings Covered
79+
80+
### Infrastructure Terms
81+
- Common available misspellings → `available`
82+
- Common backup misspellings → `backup`
83+
- Common terraform misspellings → `terraform`
84+
- Common resource misspellings → `resource`
85+
- Common configuration misspellings → `configuration`
86+
87+
### Technical Terms
88+
- Common environment misspellings → `environment`
89+
- Common performance misspellings → `performance`
90+
- Common implementation misspellings → `implementation`
91+
92+
## Troubleshooting
93+
94+
### False Positives
95+
If a legitimate word is flagged:
96+
1. Add it to `typos.toml` under `[default.extend-words]`
97+
2. Use the exact spelling: `WordName = "WordName"`
98+
99+
### Missing Spell Check
100+
If typos aren't being caught:
101+
1. Verify `typos.toml` exists and is properly formatted
102+
2. Check pre-commit hook configuration
103+
3. Ensure file types are included (`types: [markdown, text]`)
104+
105+
### Configuration Not Loading
106+
If `typos.toml` changes aren't taking effect:
107+
1. Verify the `--config typos.toml` argument in `.pre-commit-config.yaml`
108+
2. Clear pre-commit cache: `pre-commit clean`
109+
3. Reinstall hooks: `pre-commit install --install-hooks`
110+
111+
## Best Practices
112+
113+
### For Contributors
114+
1. **Run spell check before committing**:
115+
```bash
116+
pre-commit run typos --files $(git diff --cached --name-only)
117+
```
118+
119+
2. **Use consistent technical terminology**
120+
3. **Check both content and variable descriptions in .tf files**
121+
4. **Review example documentation for consistency**
122+
123+
### For Maintainers
124+
1. **Regularly update typos.toml** with new technical terms
125+
2. **Monitor for recurring misspellings** and add to configuration
126+
3. **Keep the tool version updated** in `.pre-commit-config.yaml`
127+
4. **Review spell-check failures** in CI/CD for patterns
128+
129+
## Integration with Development Workflow
130+
131+
### IDE Setup
132+
Configure your IDE/editor for spell-checking:
133+
- **VS Code**: Install Code Spell Checker extension
134+
- **IntelliJ**: Enable built-in spell checker
135+
- **Vim**: Use vim-spell plugin
136+
137+
### Git Hooks
138+
Pre-commit hooks automatically run spell-check on:
139+
- All staged markdown files
140+
- Text files in the repository
141+
- Documentation updates
142+
143+
### CI/CD Integration
144+
Spell-checking is integrated into:
145+
- Pre-commit CI workflow
146+
- Pull request validation
147+
- Release preparation checks
148+
149+
## Support
150+
151+
If you encounter spell-check issues:
152+
1. Check this guide first
153+
2. Review `typos.toml` configuration
154+
3. Test with manual pre-commit run
155+
4. Create an issue if problems persist
156+
157+
Remember: Good spelling improves documentation quality and user experience!

‎.pre-commit-config.yaml‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -57,5 +57,6 @@ repos:
5757
rev: v1.16.23
5858
hooks:
5959
- id: typos
60-
types: [markdown]
61-
args: ['--format', 'brief']
60+
types: [markdown, text]
61+
args: ['--format', 'long', '--config', 'typos.toml']
62+
exclude: '^test_.*\.md$|.*test_formatting.*'

‎README.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -230,6 +230,51 @@ In case you get an error message similar to this one:
230230
error creating Backup Vault (): AccessDeniedException: status code: 403, request id: 8e7e577e-5b74-4d4d-95d0-bf63e0b2cc2e,
231231
```
232232

233+
Add the [required IAM permissions mentioned in the CreateBackupVault row](https://docs.aws.amazon.com/aws-backup/latest/devguide/access-control.html#backup-api-permissions-ref) to the role or user creating the Vault (the one running Terraform CLI). In particular make sure `kms` and `backup-storage` permissions are added.
234+
<!-- END_TF_DOCS -->
235+
236+
## Known Issues
237+
238+
During the development of the module, the following issues were found:
239+
240+
### Error creating Backup Vault
241+
242+
In case you get an error message similar to this one:
243+
244+
```
245+
error creating Backup Vault (): AccessDeniedException: status code: 403, request id: 8e7e577e-5b74-4d4d-95d0-bf63e0b2cc2e,
246+
```
247+
248+
Add the [required IAM permissions mentioned in the CreateBackupVault row](https://docs.aws.amazon.com/aws-backup/latest/devguide/access-control.html#backup-api-permissions-ref) to the role or user creating the Vault (the one running Terraform CLI). In particular make sure `kms` and `backup-storage` permissions are added.
249+
<!-- END_TF_DOCS -->
250+
251+
## Known Issues
252+
253+
During the development of the module, the following issues were found:
254+
255+
### Error creating Backup Vault
256+
257+
In case you get an error message similar to this one:
258+
259+
```
260+
error creating Backup Vault (): AccessDeniedException: status code: 403, request id: 8e7e577e-5b74-4d4d-95d0-bf63e0b2cc2e,
261+
```
262+
263+
Add the [required IAM permissions mentioned in the CreateBackupVault row](https://docs.aws.amazon.com/aws-backup/latest/devguide/access-control.html#backup-api-permissions-ref) to the role or user creating the Vault (the one running Terraform CLI). In particular make sure `kms` and `backup-storage` permissions are added.
264+
<!-- END_TF_DOCS -->
265+
266+
## Known Issues
267+
268+
During the development of the module, the following issues were found:
269+
270+
### Error creating Backup Vault
271+
272+
In case you get an error message similar to this one:
273+
274+
```
275+
error creating Backup Vault (): AccessDeniedException: status code: 403, request id: 8e7e577e-5b74-4d4d-95d0-bf63e0b2cc2e,
276+
```
277+
233278
Add the [required IAM permissions mentioned in the CreateBackupVault row](https://docs.aws.amazon.com/aws-backup/latest/devguide/access-control.html#backup-api-permissions-ref) to the role or user creating the Vault (the one running Terraform CLI). In particular make sure `kms` and `backup-storage` permissions are added.
234279

235280
## Testing

‎typos.toml‎

Lines changed: 33 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,36 @@
11
[default.extend-words]
2-
# HashiCorp is the correct company name, not a typo
2+
# Company names
33
HashiCorp = "HashiCorp"
44
Hashi = "Hashi"
5+
6+
# Common misspellings of "available"
7+
avaialble = "available"
8+
availabel = "available"
9+
avalable = "available"
10+
avilable = "available"
11+
availble = "available"
12+
availabe = "available"
13+
14+
# Common misspellings of "availability"
15+
availabilty = "availability"
16+
availabiliy = "availability"
17+
availabiltiy = "availability"
18+
19+
# AWS and Infrastructure terms
20+
backpu = "backup"
21+
backups = "backups"
22+
terrafrom = "terraform"
23+
terrafrm = "terraform"
24+
resurce = "resource"
25+
resrouce = "resource"
26+
resouce = "resource"
27+
configuraton = "configuration"
28+
confguration = "configuration"
29+
30+
# Technical terms
31+
enviroment = "environment"
32+
enviromental = "environmental"
33+
perfomance = "performance"
34+
performace = "performance"
35+
implmentation = "implementation"
36+
implementaion = "implementation"

0 commit comments

Comments
 (0)