Add check-spelling to a repository
Tags: actionshackathon21
Published: 2021-12-03 01:47:14



Everyone wonders why I care about spelling. Sometimes the rewards are :beer::
> This typo is epic, you just made my day! :rofl: 
>
> I never would've imagined that a MR with hundreds of typo fixes would have any real impact, but you made it happen.  It turns out the EDNS keepalive module didn't work because of this typo (and no one noticed...) And you fixed it, thank you!
>
> We owe you a beer! :beers:
>
> _Originally posted by @tomaskrizek in https://github.com/CZ-NIC/knot-resolver/pull/75#discussion_r752569877_

Sadly, the spell checker shows that there just aren't enough :eyes: (["Given enough eyeballs, all bugs are shallow."](https://quotepark.com/quotes/1728076-eric-s-raymond-given-enough-eyeballs-all-bugs-are-shallow/)):
> Oh wow!  This is a lesser used portion of the Chocolatey application, but I would have still expected for this to have been caught before now.  This change makes sense to me.
>
> _Originally posted by @gep13 in https://github.com/chocolatey/choco/pull/2466#discussion_r755506047_
### My Workflow
https://github.com/check-spelling/spell-check-this/blob/main/.github/workflows/spelling.yml

The workflow is built around {% github https://github.com/check-spelling/check-spelling %} [Marketplace Actions Check spelling
](https://github.com/marketplace/actions/check-spelling)

### Submission Category: 

Maintainer Must-Haves

### Yaml File or Link to Code

The [workflow](
https://github.com/check-spelling/spell-check-this/blob/main/.github/workflows/spelling.yml) has a couple of interesting pieces:

1. It can check both a push and a pull request.
1. If there's an existing pull request, the action will skip checking the push to save computing resources.
1. Permissions are reduced during the check phase for security reasons.
1. It's possible to only check changed files.
1. The action generates outputs which enables one to consume them in ways I couldn't otherwise imagine.
1. There's a separate comment phase as commenting requires additional permissions. (This is the default way that the workflow consumes the action's outputs and then sends them back to the action.)
1. It's possible to ask the workflow to update its own metadata.
1. When it updates the metadata, it collapses its original comment and your note to update the metadata.
1. I recently added a note as part of this last phase linking users to a file they can edit in order to trigger a new validation pass.

### Journey

I've been working on this tool for a while.

You can use it just for your documentation (as PowerDNS does), or you can use it for your entire project.

In the second half of this year, I've significantly improved its performance (it wasn't bad for small to medium repositories, but it wasn't good enough for giant ones, it's now doing reasonably well there), including allowing concurrency at the process level and via matrix runs.

I've also been adding additional heuristics, such as recognizing when a file really isn't worth checking -- often it will identify translation files and binaries as things to skip. I ran across a couple of projects with source code files that were >10 MB, so there's logic to skip such files by default (you can tune the threshold).

There are now heuristics to identify supplemental dictionaries one could use to reduce the size of the in-repository metadata. (The heuristics run if there are unrecognized terms, but you can turn them off if you don't want them.)

I'm slowly working on adjusting the action so that it could check other languages (hopefully next year).

I regularly feed projects to the template and am growing a list of [pattern templates](https://github.com/check-spelling/check-spelling/wiki/Configuration-Examples:-patterns) to make it easy for projects to trim out noise.

For medium-sized projects, the tool will regularly find bugs, whether it's a broken public API or a test that isn't testing what it thought it was testing. These are all normal occurrences. Consistent spelling helps projects avoid such pitfalls.

### Hooks

#### Auto-detecting dictionary words

Because the workflow is customizable, I'm playing with instance-specific customizations such as [this one](https://github.com/ohmyzsh/ohmyzsh/commit/733ac0a85b56d57516355d4c39a031291beb7d5e) for [ohmyzsh/ohmyzsh](https://github.com/ohmyzsh/ohmyzsh). As ohmyzsh is built around aliases for zsh, this additional commit would automatically recognize aliases before the spell checker runs and add them to the dictionary. This means that if the alias is used in the documentation (and hopefully it is!), it'll be automatically accepted as a word, and when someone misspells an alias, that misspelling will stick out.

https://github.com/ohmyzsh/ohmyzsh/blob/e6657a8b5524c0a4893bd6bcbf9cf0234a07e155/.github/workflows/spelling.yml#L33-L40

```yml
    - name: find aliases
      run: |
        for a in $(git ls-files|grep '\.zsh$'); do
          echo "-- $a"
          if [ -s "$a" ]; then
            perl -ne 'next unless s/^alias ([A-Za-z]{3,})=.*/$1/;print' "$a" | tee -a .github/actions/spelling/allow.txt
          fi
        done;
```

This logic:
1. Looks for `.zsh` script files.
2. Reports the name of the file from which it's going to be getting terms.
3. Ensures there's a file with content (there's currently a [quirk](https://github.com/nektos/act/issues/912) in `act` where a file tracked by git that matches `.gitignore` will not be copied into the `act` environment).
4. Looks for lines that start with `alias ` and have at least 3 characters.
5. Reports each item and adds them to the dictionary.

I've submitted this as [ohmyzsh/ohmyzsh#10475](https://github.com/ohmyzsh/ohmyzsh/pull/10475).

### Neat things

#### GitLab via `act`

I know at least one project that runs check-spelling using [nektos/act](https://github.com/nektos/act) in [GitLab](https://gitlab.com/). Because of the support for outputs, it would be possible for the act workflow to take the outputs and wire them to an equivalent commenting GitLab mechanism.

### Recent deployments

#### dev.to

This blog is hosted by [dev.to](https://dev.to) which is a deployment of: {% github https://github.com/forem/forem/ %}

So, I set up a deployment of check-spelling for forem: https://github.com/check-spelling/forem/actions

It doesn't take much work to convert the output into a list of words to correct (I use [Google Sheets](https://sheets.google.com) to generate corrections):

> Thanks for all the work in this PR @jsoref! Since this is quite a big PR, could you maybe break it down into smaller ones? I'd really like to get some things that are actual bugs (like this one) out faster.

_Originally posted by @citizen428 in https://github.com/forem/forem/pull/15670#discussion_r762683014_

> @jsoref The most important one to me would be everything that is 
> 1. actual code, not a comment (`currrentTime`, `onkeykup`, etc.)
> 2. not in a migration
>
> Once we have that out of the way we can think about how to slice and dice the rest.

_Originally posted by @citizen428 in https://github.com/forem/forem/pull/15670#discussion_r762689579_

That was quickly merged. I've now updated the remainder and split it into two more pieces...

#### microsoft/PowerToys

I got a ping about some items that weren't being matched in 
{% github https://github.com/microsoft/PowerToys %}

So, I made a [quick update](
https://github.com/microsoft/PowerToys/pull/14873) for it.

### Additional Resources / Info

There are a number of deployments including:
* Microsoft/[terminal](https://github.com/microsoft/terminal/), [powertoys](https://github.com/microsoft/powertoys), [winget-cli](https://github.com/microsoft/winget-cli)
* [PowerDNS/pdns](https://github.com/powerdns/pdns/)
* [NASA/fprime (F')](https://github.com/nasa/fprime)