[ovs-dev] Documentation: Add section on inclusive language.

As a community we should strive to be inclusive.
As such it seems appropriate to adopt an word list,
to help guide the use of inclusive language.

This patch proposes use of the Inclusive Naming Word List v1.0.

Link: https://inclusivenaming.org/word-lists/
Signed-off-by: Simon Horman <horms@ovn.org>
---
 Documentation/automake.mk                     |  1 +
 Documentation/index.rst                       |  1 +
 .../contributing/inclusive-language.rst       | 58 +++++++++++++++++++
 .../internals/contributing/index.rst          |  1 +
 4 files changed, 61 insertions(+)
 create mode 100644 Documentation/internals/contributing/inclusive-language.rst

Simon Horman <horms@ovn.org> writes:

> As a community we should strive to be inclusive.
> As such it seems appropriate to adopt an word list,
> to help guide the use of inclusive language.
>
> This patch proposes use of the Inclusive Naming Word List v1.0.
>
> Link: https://inclusivenaming.org/word-lists/
> Signed-off-by: Simon Horman <horms@ovn.org>
> ---

I think it's a good practice to adopt a list that gets vetted.  I think
the inclusive naming initiative is a good choice to adopt.

For that:

Acked-by: Aaron Conole <aconole@redhat.com>

Some terms that are on the 'replace immediately' list (such as
'whitelist' and 'abort' - although the latter is considered as not a
first-order concern).  I guess we should also include some kind of
effort to clean these up as well.

>  Documentation/automake.mk                     |  1 +
>  Documentation/index.rst                       |  1 +
>  .../contributing/inclusive-language.rst       | 58 +++++++++++++++++++
>  .../internals/contributing/index.rst          |  1 +
>  4 files changed, 61 insertions(+)
>  create mode 100644 Documentation/internals/contributing/inclusive-language.rst
>
> diff --git a/Documentation/automake.mk b/Documentation/automake.mk
> index 8bd3dbb2b883..47d2e336a0b9 100644
> --- a/Documentation/automake.mk
> +++ b/Documentation/automake.mk
> @@ -109,6 +109,7 @@ DOC_SOURCE = \
>  	Documentation/internals/security.rst \
>  	Documentation/internals/contributing/index.rst \
>  	Documentation/internals/contributing/backporting-patches.rst \
> +	Documentation/internals/contributing/inclusive-language.rst \
>  	Documentation/internals/contributing/coding-style.rst \
>  	Documentation/internals/contributing/coding-style-windows.rst \
>  	Documentation/internals/contributing/documentation-style.rst \
> diff --git a/Documentation/index.rst b/Documentation/index.rst
> index 3cdc87c69845..7041384733d8 100644
> --- a/Documentation/index.rst
> +++ b/Documentation/index.rst
> @@ -43,6 +43,7 @@ Contributing
>  
>      - :doc:`internals/contributing/submitting-patches`
>      - :doc:`internals/contributing/backporting-patches`
> +    - :doc:`internals/contributing/inclusive-language`
>      - :doc:`internals/contributing/coding-style`
>      - :doc:`internals/contributing/coding-style-windows`
>  
> diff --git a/Documentation/internals/contributing/inclusive-language.rst b/Documentation/internals/contributing/inclusive-language.rst
> new file mode 100644
> index 000000000000..e8ee0958b519
> --- /dev/null
> +++ b/Documentation/internals/contributing/inclusive-language.rst
> @@ -0,0 +1,58 @@
> +..
> +      Licensed under the Apache License, Version 2.0 (the "License"); you may
> +      not use this file except in compliance with the License. You may obtain
> +      a copy of the License at
> +
> +          http://www.apache.org/licenses/LICENSE-2.0
> +
> +      Unless required by applicable law or agreed to in writing, software
> +      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
> +      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
> +      License for the specific language governing permissions and limitations
> +      under the License.
> +
> +      Convention for heading levels in Open vSwitch documentation:
> +
> +      =======  Heading 0 (reserved for the title in a document)
> +      -------  Heading 1
> +      ~~~~~~~  Heading 2
> +      +++++++  Heading 3
> +      '''''''  Heading 4
> +
> +      Avoid deeper levels because they do not render well.
> +
> +==================
> +Inclusive Language
> +==================
> +
> +In order to help facilitate an inclusive environment in the Open vSwitch
> +community we recognise the role of language in framing our
> +communication with each other. It is important that terms that
> +may exclude people through racial, cultural or other bias, are avoided
> +as they may make people feel excluded.
> +
> +We recognise that this is subjective, and to some extent is a journey.
> +But we also recognise that we cannot begin that journey without taking
> +positive action. To this end Open vSwitch is adopting the practice
> +of an inclusive word list, which helps to guide the use of language within
> +the project.
> +
> +.. _word list:
> +
> +Word List
> +---------
> +
> +The intent of this document is to formally document the acceptance of a
> +inclusive word list by Open vSwitch.  Accordingly, this document specifies
> +use of the use the `Inclusive Naming Word List
> +<https://inclusivenaming.org/word-lists/>`__ v1.0 (the word list) for Open
> +vSwitch.
> +
> +The adoption of the word list intended that this act as a guide for
> +developers creating patches to the Open vSwitch repository, including both
> +source code and documentation. And to aid maintainers in their role of
> +shepherding changes into the repository.
> +
> +Further steps to align usage of language in Open vSwitch, including
> +clarification of application of the word list, to new and existing work,
> +may follow.
> diff --git a/Documentation/internals/contributing/index.rst b/Documentation/internals/contributing/index.rst
> index a46cb046a0f5..91304e60bdc6 100644
> --- a/Documentation/internals/contributing/index.rst
> +++ b/Documentation/internals/contributing/index.rst
> @@ -35,4 +35,5 @@ The below guides provide information on contributing to Open vSwitch itself.
>     coding-style
>     coding-style-windows
>     documentation-style
> +   inclusive-language
>     libopenvswitch-abi

On 14.12.23 23:06, Aaron Conole wrote:
> Simon Horman <horms@ovn.org> writes:
>
>> As a community we should strive to be inclusive.
>> As such it seems appropriate to adopt an word list,
>> to help guide the use of inclusive language.
>>
>> This patch proposes use of the Inclusive Naming Word List v1.0.
>>
>> Link: https://inclusivenaming.org/word-lists/
>> Signed-off-by: Simon Horman <horms@ovn.org>
>> ---
> I think it's a good practice to adopt a list that gets vetted.  I think
> the inclusive naming initiative is a good choice to adopt.
>
> For that:
>
> Acked-by: Aaron Conole <aconole@redhat.com>
>
> Some terms that are on the 'replace immediately' list (such as
> 'whitelist' and 'abort' - although the latter is considered as not a
> first-order concern).  I guess we should also include some kind of
> effort to clean these up as well.
>

Thank you, Simon!

FYI Simon did a survey on inclusive language and compared various DEI lists [0]. In particular, the IBM Inclusive IT Language Repo [1] and Inclusive Naming Word Lists v1.0 [2] stood out because they give explanations on why certain words should be replaced or kept. The IBM list covers more terms, though the Inclusive Naming Word Lists has better rationale. Most other sources simply compile lists without giving any rationale.

[0] https://issues.redhat.com/browse/FDP-146
[1] https://github.com/IBM/IBMInclusiveITLanguage
[2] https://inclusivenaming.org/word-lists/

Acked-by: Jakob Meng <jmeng@redhat.com>

On 14 Dec 2023, at 15:19, Simon Horman wrote:

> As a community we should strive to be inclusive.
> As such it seems appropriate to adopt an word list,
> to help guide the use of inclusive language.
>
> This patch proposes use of the Inclusive Naming Word List v1.0.
>
> Link: https://inclusivenaming.org/word-lists/
> Signed-off-by: Simon Horman <horms@ovn.org>

Thanks for getting this started Simon. Would it make sense to enhance our checkpatch utility to scan for Tear 1/2/3 words?

Acked-by: Eelco Chaudron <echaudro@redhat.com>

On Thu, Dec 14, 2023 at 02:19:14PM +0000, Simon Horman wrote:
> As a community we should strive to be inclusive.
> As such it seems appropriate to adopt an word list,
> to help guide the use of inclusive language.
> 
> This patch proposes use of the Inclusive Naming Word List v1.0.
> 
> Link: https://inclusivenaming.org/word-lists/
> Signed-off-by: Simon Horman <horms@ovn.org>

Applied.

- Documentation: Add section on inclusive language.
  https://github.com/openvswitch/ovs/commit/df5e5cf4318a

On Thu, Dec 14, 2023 at 05:06:18PM -0500, Aaron Conole wrote:
> Simon Horman <horms@ovn.org> writes:
> 
> > As a community we should strive to be inclusive.
> > As such it seems appropriate to adopt an word list,
> > to help guide the use of inclusive language.
> >
> > This patch proposes use of the Inclusive Naming Word List v1.0.
> >
> > Link: https://inclusivenaming.org/word-lists/
> > Signed-off-by: Simon Horman <horms@ovn.org>
> > ---
> 
> I think it's a good practice to adopt a list that gets vetted.  I think
> the inclusive naming initiative is a good choice to adopt.
> 
> For that:
> 
> Acked-by: Aaron Conole <aconole@redhat.com>
> 
> Some terms that are on the 'replace immediately' list (such as
> 'whitelist' and 'abort' - although the latter is considered as not a
> first-order concern).  I guess we should also include some kind of
> effort to clean these up as well.

Thanks Aaron,

I agree that is a logical next step.
I'll add it to my todo list.

On Thu, Dec 21, 2023 at 09:12:52AM +0100, Eelco Chaudron wrote:
> 
> 
> On 14 Dec 2023, at 15:19, Simon Horman wrote:
> 
> > As a community we should strive to be inclusive.
> > As such it seems appropriate to adopt an word list,
> > to help guide the use of inclusive language.
> >
> > This patch proposes use of the Inclusive Naming Word List v1.0.
> >
> > Link: https://inclusivenaming.org/word-lists/
> > Signed-off-by: Simon Horman <horms@ovn.org>
> 
> Thanks for getting this started Simon. Would it make sense to enhance our checkpatch utility to scan for Tear 1/2/3 words?

Thanks Eelco,

I think that we should aim to avoid introducing new instances of
such words. And to that end, I think enhancing tooling such as checkpatch
is an excellent idea.

On 12/21/23 14:50, Simon Horman wrote:
> On Thu, Dec 21, 2023 at 09:12:52AM +0100, Eelco Chaudron wrote:
>>
>>
>> On 14 Dec 2023, at 15:19, Simon Horman wrote:
>>
>>> As a community we should strive to be inclusive.
>>> As such it seems appropriate to adopt an word list,
>>> to help guide the use of inclusive language.
>>>
>>> This patch proposes use of the Inclusive Naming Word List v1.0.
>>>
>>> Link: https://inclusivenaming.org/word-lists/
>>> Signed-off-by: Simon Horman <horms@ovn.org>
>>
>> Thanks for getting this started Simon. Would it make sense to enhance our checkpatch utility to scan for Tear 1/2/3 words?
> 
> Thanks Eelco,
> 
> I think that we should aim to avoid introducing new instances of
> such words. And to that end, I think enhancing tooling such as checkpatch
> is an excellent idea.

These two sentences are a bit contradictory, unless we can add a check
without maintaining a list of words ourselves.  Sounds tricky taking
into account that checkpatch script shouldn't make any network requests.

Best regards, Ilya Maximets.

Ilya Maximets <i.maximets@ovn.org> writes:

> On 12/21/23 14:50, Simon Horman wrote:
>> On Thu, Dec 21, 2023 at 09:12:52AM +0100, Eelco Chaudron wrote:
>>>
>>>
>>> On 14 Dec 2023, at 15:19, Simon Horman wrote:
>>>
>>>> As a community we should strive to be inclusive.
>>>> As such it seems appropriate to adopt an word list,
>>>> to help guide the use of inclusive language.
>>>>
>>>> This patch proposes use of the Inclusive Naming Word List v1.0.
>>>>
>>>> Link: https://inclusivenaming.org/word-lists/
>>>> Signed-off-by: Simon Horman <horms@ovn.org>
>>>
>>> Thanks for getting this started Simon. Would it make sense to
>>> enhance our checkpatch utility to scan for Tear 1/2/3 words?
>> 
>> Thanks Eelco,
>> 
>> I think that we should aim to avoid introducing new instances of
>> such words. And to that end, I think enhancing tooling such as checkpatch
>> is an excellent idea.
>
> These two sentences are a bit contradictory, unless we can add a check
> without maintaining a list of words ourselves.  Sounds tricky taking
> into account that checkpatch script shouldn't make any network requests.

Yes, I agree.  I'm not sure what the best approach would be other than
having the build / configure process pull such a list?  But even then, I
prefer we don't do such network requests when making builds (for
example, if they fail then the build fails).  Maybe we have a manual
copy of such list and periodically update it.  IE: we try to pull the
json file from the inclusive language site and then commit that to the
aux build area.

It needs some kind of agreement to switch checkpatch to make network
requests, but I don't think it is completely banned idea.  For example,
we could make such an option as an optional behavior (the way the
current spellchecking code works), but I (generally) wouldn't want to
run without it - and I would probably set the robot to do this as well.

> Best regards, Ilya Maximets.
> _______________________________________________
> dev mailing list
> dev@openvswitch.org
> https://mail.openvswitch.org/mailman/listinfo/ovs-dev