From ea24d593e921c1e35fe281b9c1de449ab7b5c56f Mon Sep 17 00:00:00 2001 From: Mark Michelson Date: Tue, 20 Aug 2024 14:03:39 -0400 Subject: [PATCH] Documentation: Add inclusive-language documentation. A recent series of commits to OVN made some changes to the language used in code, comments, and documentation to be more inclusive. This constitutes a follow-up that clarifies in the documentation what the policy is and where the list of words to avoid can be found. When starting this task, I found a commit to OVS [1] written by Simon Horman that added basically everything I wanted to say. With Simon's permission, I have copied the contents of that commit, changing all instances of "Open vSwitch" to "OVN". Simon is credited as a co-author on this commit. [1] https://github.com/openvswitch/ovs/commit/df5e5cf4318a Signed-off-by: Mark Michelson Co-authored-by: Simon Horman Acked-by: Simon Horman Signed-off-by: Mark Michelson --- Documentation/automake.mk | 1 + Documentation/index.rst | 1 + .../contributing/inclusive-language.rst | 57 +++++++++++++++++++ .../internals/contributing/index.rst | 1 + 4 files changed, 60 insertions(+) create mode 100644 Documentation/internals/contributing/inclusive-language.rst diff --git a/Documentation/automake.mk b/Documentation/automake.mk index c6cc37e495..5f7500fb76 100644 --- a/Documentation/automake.mk +++ b/Documentation/automake.mk @@ -56,6 +56,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/documentation-style.rst \ Documentation/internals/contributing/submitting-patches.rst \ diff --git a/Documentation/index.rst b/Documentation/index.rst index 04e7575058..9fb298c283 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -81,6 +81,7 @@ Learn more about the Open Virtual Network (OVN) project and about how you can co - **Contributing:** :doc:`internals/contributing/submitting-patches` | :doc:`internals/contributing/backporting-patches` | + :doc:`internals/contributing/inclusive-language` | :doc:`internals/contributing/coding-style` - **Maintaining:** :doc:`internals/maintainers` | diff --git a/Documentation/internals/contributing/inclusive-language.rst b/Documentation/internals/contributing/inclusive-language.rst new file mode 100644 index 0000000000..65e9c4fbd6 --- /dev/null +++ b/Documentation/internals/contributing/inclusive-language.rst @@ -0,0 +1,57 @@ +.. + 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 OVN 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 OVN +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 OVN 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 OVN. Accordingly, this document specifies +use of the use the `Inclusive Naming Word List +`__ v1.0 (the word list) for +OVN. + +The adoption of the word list intended that this act as a guide for +developers creating patches to the OVN 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 OVN, 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 ba6b6094e1..9dab481105 100644 --- a/Documentation/internals/contributing/index.rst +++ b/Documentation/internals/contributing/index.rst @@ -31,6 +31,7 @@ The below guides provide information on contributing to OVN itself. :maxdepth: 2 submitting-patches + inclusive-language backporting-patches coding-style documentation-style