woke

woke

woke is a text file analysis tool that detects non-inclusive language in your source code.

Creating an inclusive work environment is imperitive to a healthy, supportive, and productive culture, and an environment where everyone feels welcome and included.

woke's purpose is to point out places where improvements can be made by removing non-inclusive language and replacing it with more inclusive alternatives.

Companies like GitHub, Twitter, and Apple are already pushing these changes.

Installation

Using woke is straightforward. First, use go get to install the latest version (requires go, more instructions for non-go installation coming soon).

go get -u github.com/caitlinelfring/woke

woke should be installed to $GOPATH/bin/woke.

Usage

$ woke --help

woke is a linter that will check your source code for usage of non-inclusive
language and provide suggestions for alternatives. Rules can be customized
to suit your needs.

Provide a list of comma-separated file globs for files you'd like to check.

Usage:
  woke (file globs to check) [flags]

Flags:
      --exit-1-on-failure    Exit with exit code 1 on failures. Otherwise, will always exit 0 if any failures occur
  -h, --help                 help for woke
  -r, --rule-config string   YAML file with list of rules (default "default.yaml")

File globs

By default, woke will run against all text files in your current directory. To change this, supply a comma-separated list of globs as the first argument.

This can be something like **/*.go, or a comma-separated list of filenames.

$ woke test.txt
[test.txt:2:2] Instead of 'Blacklist', consider the following alternative(s): 'denylist,blocklist'
[test.txt:3:2] Instead of 'White-list', consider the following alternative(s): 'allowlist'
[test.txt:4:2] Instead of 'whitelist', consider the following alternative(s): 'allowlist'
[test.txt:5:2] Instead of 'blacklist', consider the following alternative(s): 'denylist,blocklist'

Rules

A set of default rules is provided in example.yaml. You can supply your own rules with -r path/to/rules.yaml

The syntax for rules is very basic. You just need a name, a regex used to match, and a string of alternatives.

rules:
  - name: whitelist
    regexp: \b(white-?list)\b
    alternatives: allowlist

Ignoring files

In your config file, you can ignore files by adding:

ignore_files:
  - .git/*
  - other/files/in/repo
  - globs/too/*

woke will also automatically ignore anything listed in .gitignore.

woke uses gobwas/glob to parse ignore globs. See link for more details on matching

Exit Code

By default, woke will exit with a successful exit code when there are any rule failures. The idea is, if you run woke on PRs, you may not want to block a merge, but you do want to inform the author that they can make better word choices.

If you're using work on PRs, you can choose to enforce these rules with a non-zero exit code, but running work --exit-1-on-failure.

TODO

• Benchmarking
• Tests
• What happens when run on a large repo?
• GitHub Actions
• More rules

Resources

• https://buffer.com/resources/inclusive-language-tech/
• https://medium.com/pm101/inclusive-language-guide-for-tech-companies-and-startups-f5b254d4a5b7
• https://www.marketplace.org/2020/06/17/tech-companies-update-language-to-avoid-offensive-terms/
• https://tools.ietf.org/html/draft-knodel-terminology-02

License

This application is licensed under the MIT License, you may obtain a copy of it here.