Use GitHub Actions for more inclusive words

Originally published on: https://developer.ibm.com/blogs/words-really-matter-github-action-enforces-inclusive-word-choice-in-markdown

As emphasized in the recent blog post by Dale Davis Jones and Tim Humphrey - Words Matter: Driving Thoughtful Change Toward Inclusive Language in Technology, in today’s development world, we use words in our common vocabulary that have problematic histories. Common terms have negative and divisive origins, and it’s our responsibility as developers to change them. While it takes time to remove defaulted terminology, we created a project to begin to programmatically enforce better word choices.

Words-Really-Matter is a GitHub Action that will scan any of your Markdown documents on GitHub and automatically create a pull request to suggest better word choices in your documentation. By default, the action itself will run on a specified branch and on any push you make. The resulting pull request may not be perfect, but we hope it’s a starting point in the right direction.

How it works

Curious to know how it works? It’s just bash! Below is the bulk of the logic and code for the action. It finds all Markdown files in your repository and looks for any instances of words that are determined to be problematic. We thought about making it case insensitive, but did not want to suggest possible changes to mission-critical code.

dict=( ["master"]="leader" ["slave"]="follower"
       ["blacklist"]="denylist" ["whitelist"]="allowlist"
       ["grandfathered"]="legacy" ["guys"]="folks")

for i in "${!dict[@]}"
do
    echo "$i"="${dict[$i]}"

    for j in $(ag --ignore-dir={.git} --ignore=entrypoint.sh -G ".md" -l $i .);
    do
        sed -i "s/$i/${dict[$i]}/g" $j
    done
done

You could run this script locally, of course, but why not leverage GitHub Actions to do the work for you? We have an example repository set up, and you can view the suggested PR.

Use the action and submit other problematic words

We hope you’re able to use this GitHub Action to influence your documentation and create a more inclusive dialog. We’re happy to accept pull requests to the repo for additional words or suggestions. We’re also happy if folks fork the repo to create their own version of this action.