ResInsight/docs/spell-checking.md

Spell Checking Workflows

ResInsight uses automated spell checking to maintain code quality and catch typos in code, comments, and documentation.

Two Workflows

1. spell-check.yml (Full Repository Check)

When it runs: On every push to any branch

What it does:

• Checks all code in four directories:
  • ApplicationExeCode/
  • ApplicationLibCode/
  • Fwk/AppFwk/
  • GrpcInterface/
• Uses codespell to find and suggest fixes for typos
• Automatically creates a PR with fixes if typos are found
• PR will be created on a branch named spell-check-patches-*

Use case: Regular maintenance and keeping the entire codebase clean

2. spell-check-pr.yml (PR Review Check)

When it runs: On pull requests that modify files in the target directories

What it does:

• Only checks files that were changed in the PR
• Uses codespell for spell checking
• Checks these file types: .cpp, .h, .inl, .py, .md, .txt, .cmake, .yml, .yaml
• Skips binary files: .svg, .xml, .json
• Fails the PR check if typos are found (must be fixed before merge)

Use case: Preventing new typos from being introduced in PRs

Configuration Files

.codespellrc

Central configuration file for codespell that defines:

• Files to skip (e.g., SVG, JSON, XML files)
• Ignore words file location
• Default directories to check
• File types to include
• Output formatting options

This configuration is automatically used by both GitHub workflows and local runs.

.codespell-ignore

Used by codespell (both workflows). Contains domain-specific terms that should not be flagged:

• Petroleum engineering terms: perm, porosity, wellbore, facies
• Eclipse file formats: EGRID, INIT, UNRST, SMSPEC
• Simulation tools: Abaqus, ODB, VTK
• Common abbreviations: API, GUI, RGB, CSV
• Units: ft, mD, bbl, psi

To add a word: Simply add it to .codespell-ignore (one word per line, comments start with #)

How to Fix Typos

From Full Repository Check

When the spell-check workflow creates a PR:

1. Review the PR created by the workflow
2. Check if the suggested changes are correct
3. If correct: merge the PR
4. If incorrect: close the PR and add the word to .codespell-ignore

From PR Review Check

When your PR fails the spell check:

1. Read the error message to see which words are flagged
2. Fix the typos in your code OR
3. If the word is correct (domain-specific term), add it to .codespell-ignore
4. Push the changes to your PR
5. The check will run again automatically

Common Domain Terms Already Whitelisted

The following are already in the whitelist:

• Reservoir simulation: perm, permeability, porosity, geomech, seismic
• Eclipse formats: EGRID, GRID, INIT, UNRST, SMSPEC, ESMRY
• Tools: Abaqus, ODB, VTK, OSDU, FMU, VFP
• Abbreviations: Md, Tvd, Rkb, Rft, Plt
• Organizations: ResInsight, Equinor, Ceetron, OPM

Testing Locally

You can run spell checks locally before pushing:

Using codespell (recommended for quick checks)

# Install codespell
pip install codespell

# Check specific files (uses .codespellrc automatically)
codespell myfile.cpp

# Check a directory (uses .codespellrc automatically)
codespell ApplicationLibCode/

# Check all default directories (defined in .codespellrc)
codespell

# Apply fixes automatically (use with caution)
codespell --write-changes

# Override config file settings if needed
codespell --ignore-words=custom-ignore.txt --skip="*.log,*.tmp" myfile.cpp

Troubleshooting

False Positives

If a word is flagged but is correct:

1. Add it to .codespell-ignore

Words That Should Be Fixed

If the spell checker suggests a change that seems wrong, check:

• Is the word used correctly in context?
• Is it a technical term that should be in the whitelist?
• Is there a better/clearer word to use?

Workflow Not Running

• Check that your changes touch files in the monitored directories
• Check that the file extensions are supported
• Look at the GitHub Actions tab for error messages