Automate checking inclusive language coding guideline

zephyrproject-rtos / zephyr

Primary Git Repository for the Zephyr Project. Zephyr is a new generation, scalable, optimized, secure RTOS for multiple hardware architectures.

https://docs.zephyrproject.org

Apache License 2.0

10.37k stars 6.35k forks source link

Automate checking inclusive language coding guideline #57301

Open MaureenHelm opened 1 year ago

MaureenHelm commented 1 year ago

Introduction

An inclusive language coding guideline was agreed upon by the TSC on 26 Aug 2020 and added to the documentation in #30508. Add an automatic compliance check to verify that PRs don't introduce new usage of offensive terms.

https://docs.zephyrproject.org/latest/contribute/coding_guidelines/index.html#rule-a-2-inclusive-language

Problem description

Violations of the inclusive language coding guideline currently are caught by manual inspection only and therefore are easily missed.

Example in https://github.com/zephyrproject-rtos/zephyr/pull/56800#discussion_r1177953787

Proposed change

Add a compliance check to automate checking PRs for violations of the inclusive language coding guideline.

Concerns and Unresolved Questions

How to handle PRs that modify existing usages of offensive terms?

mbolivar-nordic commented 1 year ago

@maureenhelm I noticed some violations, but those were by manual inspection. Wanted to see if there was any interest in how to add automated checking for this
@henrikbrixandersen at Vestas I believe we are using some off the shelf tools for checking text for offensive language (job ads, brochures, etc.). I can look into this
@nashif we can use checkpatch for this -- saw a PR from @nandojve on this using things like 'slv'
@maureenhelm that was in the name of the register, though, so we agreed to leave this, while changing variables. Need to deal with subtleties like this and probably leave the check at the warning level to support this
@galak I remember LF presenting something about this, maybe reach out to Brett as well
@stephanosio implementing is one thing, but we need to come up with a list of such terms
@maureenhelm we have a list that's part of the coding guidelines (https://docs.zephyrproject.org/latest/contribute/coding_guidelines/index.html#rule-a-2-inclusive-language)
@stephanosio so only these?
@nashif start with these. Can use checkpatch's spelling checks for this

mbolivar-nordic commented 1 year ago

Process WG:

put on hold for now
microsoft has a checker that seems most promising for now: https://github.com/marketplace/actions/inclusiveness-analyzer
current results in https://github.com/kartben/zephyr/actions/runs/4874272528 from @kartben

marc-hb commented 1 year ago

Standard Linux spellchecker have apparently not been mentioned yet:

https://github.com/hunspell/hunspell/issues/448 , https://linux.die.net/man/4/hunspell "the most popular spellchecker"
https://github.com/codespell-project/codespell - already used by checkpatch.pl
https://facelessuser.github.io/pyspelling/

keith-zephyr commented 2 months ago

@kartben This issue covers checking inclusive language for new code. But we need a process to address breaking changes for violations already in the tree. @nashif - We need to open issues for each area that need updates. @jfischer-no - there is a sample pulling in a 3rd party tool that adds in "slave" as part of the documentation. Tool test modbus Zephyr. How should we handle this? @kartben - The documentation should note Zephyr makes a best effort to use inclusive language and ask contributors to open issues that aren't compliant. We probably can't get rid of all instances, so a disclaimer would be helpful. @kartben - Will run the Microsoft tool to see what the status of inclusive terms in the tree. "blackbox" is a term flagged by the MS tool that should probably be allowed.