DCI Working Group: Inclusive Naming Proposal

Owned by Grace Hartley (Deactivated)
Last updated: Sept 24, 2022 by artem
3 min read
Status

APPROVED 

Blocking
Outcome
Minutes Link

Context

The Hyperledger DCI Working Group would like to propose best practices to be adopted by Hyperledger projects and labs around inclusive naming. Hyperledger continuously promotes "all are welcome here" to its community. The DCI Working Group believes one way for Hyperledger to continue to improve is by encouraging inclusive language across all of its projects. We believe language matters, especially when fostering an open source community. Updating language across the projects to be more inclusive is a powerfuk step in continuing to foster and promote diversity and inclusion in its community. This blog post provides additional context for those interested.

The DCI Working Group is recommending the Technical Steering Committee to approve the following proposal with each of these recommendations. These are recommended best practices for projects that we would suggest them to implement.

Recommendations

Recommendation #1:  We recommend all Hyperledger projects and labs update their contributor and/or documentation guidelines to have a statement referencing and encouraging inclusive language in the community's work. One example from Besu found on the Documentation Style Guide is below. Every project and lab is encouraged to copy and paste this suggestion into their contributions.

Inclusive Language: 

  • Consider that users who will read the docs are from different background and cultures and that they have different preferences.
  • Avoid potential offensive terms and, for instance, prefer "allow list and deny list" to "white list and black list".
  • We believe that we all have a role to play to improve our world, and even if writing inclusive doc might not look like a huge improvement, it's a first step in the right direction.
  • We suggest to refer to Microsoft bias free writing guidelines and Google inclusive doc writing guide as starting points.

Recommendation #2: We recommend all Hyperledger projects and labs make these specific language changes to their projects. While the DCI Working Group understands that projects should make decisions on language, we wanted to provided some specific examples they can change to encourage more inclusivity. To implement these changes, they can make updates manually or they can use the dci-lint tool (see recommendation #3) to automate these updates.

  • master → main
  • slave → replicas
  • blacklist → denylist
  • whitelist → allowlist

Recommendation #3:  We recommend that the dci-lint tool that Peter Somogyvari wrote be implemented across all Hyperledger repos. The goal of the dci-lint tool is for projects to be able to detect any language changes. This tool helps remove a barrier to entry for updating language in the projects to be more inclusive. Hyperledger staff is prepared to push this out across the various repos with no effort from maintainers. The tool does not specify which language changes to make, but it makes the process easier to implement any changes the projects would like.

Recommendation #4: Include Inclusive language as one badge in the Project Badging Proposal. This recommendation is assuming the TSC makes the decision to move forward with a project badging system. If projects meet the recommendations #1, #2, and #3 above, they can gain a badge for Inclusive Language best practices. 

Implementation Proposal:

We want these recommendations to be easy for our community members and maintainers to implement. We suggest these steps be followed:

  1. The DCI Working Group will present at a Maintainer Onboarding Meeting these DCI Recommendations to train and inform the maintainers of these best practices. We want to inform the community of the value of these practices, but also train them on how to implement them easily in their projects.
  2. Leverage the DCI Working Group to share this proposal in several forums, in addition to the Maintainer meeting, including the devweekly newsletter, project contributor meetings, etc.
  3. Add to the quarterly report template the question, "Has your project implemented these inclusive language changes listed below to your repo? Yes/No?" We will include a link to this page in which the project can get started with the linter tool to assist if they want to use it. The changes include:
    1. master → main
    2. slave → replicas
    3. blacklist → denylist
    4. whitelist → allowlist
  4. Add to the quarterly report template, "Have you added an Inclusive Language Statement to your project's documentation and/or Wiki pages?" We will include this paragraph as an example. 

    Inclusive Language: 

    • Consider that users who will read the docs are from different background and cultures and that they have different preferences.
    • Avoid potential offensive terms and, for instance, prefer "allow list and deny list" to "white list and black list".
    • We believe that we all have a role to play to improve our world, and even if writing inclusive doc might not look like a huge improvement, it's a first step in the right direction.
    • We suggest to refer to Microsoft bias free writing guidelines and Google inclusive doc writing guide as starting points.

Reviewed By: