diff options
Diffstat (limited to 'docs/design_guide.rst')
| -rw-r--r-- | docs/design_guide.rst | 39 |
1 files changed, 38 insertions, 1 deletions
diff --git a/docs/design_guide.rst b/docs/design_guide.rst index 6f87ecf79..2d52e988b 100644 --- a/docs/design_guide.rst +++ b/docs/design_guide.rst @@ -1,9 +1,11 @@ +.. role:: strike + Design Guide ============ This guide covers a variety of development practices for CircuitPython core and library APIs. These APIs are both `built-into CircuitPython -<https://github.com/adafruit/circuitpython/tree/master/shared-bindings>`_ and those that are +<https://github.com/adafruit/circuitpython/tree/main/shared-bindings>`_ and those that are `distributed on GitHub <https://github.com/search?utf8=%E2%9C%93&q=topic%3Acircuitpython&type=>`_ and in the `Adafruit <https://github.com/adafruit/Adafruit_CircuitPython_Bundle>`_ and `Community <https://github.com/adafruit/CircuitPython_Community_Bundle/>`_ bundles. Consistency with these @@ -46,6 +48,41 @@ not have the ``adafruit_`` module or package prefix. Both should have the CircuitPython repository topic on GitHub. +Terminology +----------- + +As our Code of Conduct states, we strive to use "welcoming and inclusive +language." Whether it is in documentation or in code, the words we use matter. +This means we disfavor language that due to historical and social context can +make community members and potential community members feel unwelcome. + +There are specific terms to avoid except where technical limitations require it. +While specific cases may call for other terms, consider using these suggested +terms first: + ++--------------------+---------------------+ +| Preferred | Deprecated | ++====================+=====================+ +| Main (device) | :strike:`Master` | ++--------------------+---------------------+ +| Peripheral | :strike:`Slave` | ++--------------------+ + +| Sensor | | ++--------------------+ + +| Secondary (device) | | ++--------------------+---------------------+ +| Denylist | :strike:`Blacklist` | ++--------------------+---------------------+ +| Allowlist | :strike:`Whitelist` | ++--------------------+---------------------+ + +Note that "technical limitations" refers e.g., to the situation where an +upstream library or URL has to contain those substrings in order to work. +However, when it comes to documentation and the names of parameters and +properties in CircuitPython, we will use alternate terms even if this breaks +tradition with past practice. + + .. _lifetime-and-contextmanagers: Lifetime and ContextManagers |