This page documents the automated spell check system used in the PowerToys repository. It covers the GitHub Action that runs spell checking on pull requests, the configuration files that define acceptable non-dictionary terms, and the process for maintaining those files when new technical terms are introduced.
This page is part of the broader Code Quality and CI documentation (see 7.7). It does not cover general code review processes or CI pipeline configuration.
PowerToys uses the `check-spelling` GitHub Action to automatically scan source files for misspelled words on every pull request and push. Because the codebase contains a large volume of Windows API identifiers, C++ macros, user names, and module-specific tokens that are not standard English words, the system maintains curated exception lists that the spell checker consults before flagging a word.
The configuration lives entirely under `.github/actions/spell-check/` Critically, this directory is excluded from the standard CODEOWNERS protection, meaning any contributor can modify spell-check lists without requiring review from the @microsoft/powertoys-code-owners group. The reasoning is stated directly in the CODEOWNERS file:
"Protection of the spell-check rules makes no sense as it needs to be changed in nearly every PR."
Sources: .github/CODEOWNERS1-4
Spell Check Configuration Directory Layout:
.github/
โโโ actions/
โโโ spell-check/
โโโ expect.txt โ primary exceptions list
โโโ allow/
โโโ names.txt โ module names and contributor names
โโโ code.txt โ code-domain terms by category
| File | Purpose | Approximate Size |
|---|---|---|
expect.txt | High-volume technical terms (Win32 macros, linker symbols, WiX tokens, etc.) | ~2200 entries |
allow/names.txt | PowerToys module identifiers, GitHub usernames, third-party product names | ~250 entries |
allow/code.txt | Color names, file extensions, keyboard constants, URL path segments, math functions | ~365 entries |
Sources: .github/actions/spell-check/expect.txt1-10 .github/actions/spell-check/allow/names.txt1-5 .github/actions/spell-check/allow/code.txt1-5
expect.txtThis is the primary exception list and the one most likely to require updates in PRs that introduce new Win32 API usage, WiX installer fragments, or other platform-specific identifiers. Entries are plain words, one per line, in alphabetical order.
Representative categories found in expect.txt:
| Category | Example Entries |
|---|---|
| Win32 handle types | hwnd, hbitmap, hmonitor, hresult |
| Window message names | NCHITTEST, DWMWA, WINDOWPOSCHANGED |
| WiX installer tokens | BOOTSTRAPPERINSTALLFOLDER, INSTALLFOLDER, WIXUI |
| COM / ATL identifiers | CAtl, coclass, COINIT, riid, CLSCTX |
| Windows shell constants | SFGAO, FOLDERID, SHCNE, SHELLEX |
| PowerToys-specific | cmdpal, FANCYZONESDRAWLAYOUTTEST, keyboardmanagerstate |
| CI / build tooling | azcliversion, esrp, binlog, vswhere |
| Numeric/code abbreviations | bpp, cch, dwl, luid |
The file is maintained in alphabetical order to facilitate automated sorting and to make duplicate detection straightforward during code review.
Sources: .github/actions/spell-check/expect.txt1-2224
allow/names.txtOrganized into three sections separated by comments:
# POWERTOYS โ Internal module identifiers used as directory names, setting keys, and executable names (e.g., alwaysontop, colorpicker, fancyzones, powerlauncher, shortcutguide).# USERS โ GitHub usernames of contributors who appear in changelogs, commit messages, or documentation (e.g., daverayment, htcfreek, noraa-junker).# OTHERS โ Third-party library, tool, and product names referenced in documentation or code comments (e.g., Newtonsoft, Vanara, xamlstyler, winui).Sources: .github/actions/spell-check/allow/names.txt1-249
allow/code.txtOrganized by comment-delimited sections. Each section corresponds to a domain from which non-dictionary tokens originate:
| Section | Entries |
|---|---|
# COLORS | argb, bgra, PALEBLUE, ICEBLUE, Farbraum |
# FILES | mkv, msix, nupkg, resw, resx, srt |
# FONTS | Consolas, Neue, Noto, Segoe, Roboto |
# IN URLs | accessibilityinsights, fwlink, stylecop, linkedin |
# KEYS | LAlt, LCONTROL, KBDLLHOOKSTRUCT, altdown |
# User32.SYSTEM_METRICS_INDEX.cs | CXSCREEN, CYCURSOR, DBCSENABLED |
# MATH | artanh, arsinh, arcosh, roundf |
# .NET | AOT, Aot |
# GitHub issue/PR commands | azp, feedbackhub, needinfo |
# XAML | Untargeted |
# MRU lists | MRUCMPPROC, MRUINFO, CACHEWRITE |
Sources: .github/actions/spell-check/allow/code.txt1-364
The check-spelling action reads all source files in the repository and tokenizes each word. Any token that does not appear in the action's built-in English dictionary, in expect.txt, or in any file under allow/ is treated as a potential misspelling and reported.
Spell Check Execution Flow:
Sources: .github/actions/spell-check/expect.txt1-10 .github/actions/spell-check/allow/names.txt1-5 .github/CODEOWNERS1-4
The following diagram maps each configuration file to the type of repository content it is associated with:
Sources: .github/actions/spell-check/expect.txt1-2224 .github/actions/spell-check/allow/names.txt1-249 .github/actions/spell-check/allow/code.txt1-364
A PR that introduces any of the following will typically require an update to one of the exception files:
expect.txt)allow/names.txt under # POWERTOYS)allow/names.txt under # USERS)allow/names.txt under # OTHERS)allow/code.txt under the appropriate section)expect.txt is maintained in alphabetical order. The README changelog refers to "Reordered the spell-check expect list for consistent automation," confirming that sort order is enforced.allow/names.txt and allow/code.txt are grouped under comment headers and are generally sorted within each group.hwnd (lowercase) and HWND (uppercase) are distinct entries if both forms appear in the codebase.Sources: README.md319-321 .github/actions/spell-check/expect.txt1-10
The CODEOWNERS file protects the full .github/ directory under @microsoft/powertoys-code-owners, but explicitly leaves .github/actions/spell-check/ with no listed owner. This means PR authors can merge changes to the exception lists without requiring a code owner review, which is intentional since nearly every PR that adds new technical terms needs to update these files.
# From .github/CODEOWNERS
/.github/ @microsoft/powertoys-code-owners
/.github/actions/spell-check/
Sources: .github/CODEOWNERS1-4
The table below shows representative patterns used when deciding which file a new exception belongs in:
| Token type | Target file | Example entry |
|---|---|---|
| Windows message constant (all-caps) | expect.txt | WINDOWPOSCHANGED |
| WiX installer variable | expect.txt | BOOTSTRAPPERINSTALLFOLDER |
| PowerToys module directory name | allow/names.txt (under # POWERTOYS) | colorpicker |
| GitHub contributor handle | allow/names.txt (under # USERS) | daverayment |
| External library name | allow/names.txt (under # OTHERS) | Vanara |
| Win32 keyboard constant | allow/code.txt (under # KEYS) | KBDLLHOOKSTRUCT |
| Image/video format extension | allow/code.txt (under # FILES) | mkv |
| URL path component | allow/code.txt (under # IN URLs) | fwlink |
| C++ math function | allow/code.txt (under # MATH) | artanh |
Sources: .github/actions/spell-check/expect.txt360-395 .github/actions/spell-check/allow/names.txt1-30 .github/actions/spell-check/allow/code.txt100-175
Refresh this wiki
This wiki was recently refreshed. Please wait 4 days to refresh again.