aboutcode-org / aboutcode-org/scancode-toolkit
Add codespell spell-check CI workflow to catch spelling mistakes in PRs
- Dominant language
- Python
- Stars
- 2.6k
- Forks
- 791
- Avg merge
- 1d 12h
- Merged PRs (30d)
- 5
Description
Add a GitHub Actions workflow to run **codespell** on files changed in PRs,
catching spelling mistakes in documentation and code comments before they are merged.
## Possible Labels
- new feature
- documentation
## Category
- [x] Enhancement
- [x] Documentation
## Update
Currently, there is no automated way to catch spelling mistakes in:
- Documentation files (`*.rst`, `*.md`)
- Python source code comments and docstrings (`*.py`)
- CI/build scripts and configuration files
PR #4720 fixed ~219 spelling errors manually using codespell. Automating this
check prevents regressions and catches new typos early.
Reference: https://github.com/aboutcode-org/scancode-toolkit/pull/4720#issuecomment-3840564564
### Scope (Phased Approach)
**Phase 1 (This issue):**
- Check only files changed in PRs (not entire codebase)
- Target: `.py`, `.rst`, `.md` files
- Non-blocking (warning only) initially
- Report results in GitHub Job Summary
**Phase 2 (Future):**
- Make it blocking once false-positive rate is acceptable
- Extend to `.yml`, `.sh`, `.toml` files
- Integrate with pre-commit hooks
## How This Feature helps the organization
- Prevents spelling regressions from being merged
- Catches typos in documentation before they reach users/readthedocs
- Reduces manual review effort for spelling errors
- Improves overall documentation quality and professionalism
## Implementation Details
Add a lightweight GitHub Actions workflow (`.github/workflows/spell-check.yml`) that:
1. Triggers on PRs modifying `.py`, `.rst`, or `.md` files
2. Detects changed files using `git diff`
3. Runs `codespell` only on those changed files
4. Reports results in the GitHub Job Summary (non-blocking/warning only)
Configuration:
- `setup.cfg` `[codespell]` section with built-in dictionaries and skip patterns
- `.codespell-ignore-words.txt` custom dictionary with project-specific terms
(ScanCode, nexB, PackageURL, SPDX, licensedcode, packagedcode, etc.)
- Skips `tests/`, `samples/`, `thirdparty/`, `src/licensedcode/data/rules/`
## Example/Links if Any
- [codespell documentation](https://github.com/codespell-project/codespell)
- Discussion: https://github.com/aboutcode-org/scancode-toolkit/pull/4720#issuecomment-3840564564
Contributor guide
Assessment
This issue has not been assessed yet.