Re: [Ksummit-discuss] [PATCH] CodingStyle: Inclusive Terminology
Hi Dan, and everybody, Thank you for the patch. On Sat, Jul 04, 2020 at 01:02:51PM -0700, Dan Williams wrote: > Recent events have prompted a Linux position statement on inclusive > terminology. Given that Linux maintains a coding-style and its own > idiomatic set of terminology here is a proposal to answer the call to > replace non-inclusive terminology. > > Cc: Jonathan Corbet > Cc: Kees Cook > Signed-off-by: Chris Mason > Signed-off-by: Greg Kroah-Hartman > Signed-off-by: Dan Williams > --- > Documentation/process/coding-style.rst | 12 > Documentation/process/inclusive-terminology.rst | 64 > +++ > Documentation/process/index.rst |1 > 3 files changed, 77 insertions(+) > create mode 100644 Documentation/process/inclusive-terminology.rst > > diff --git a/Documentation/process/coding-style.rst > b/Documentation/process/coding-style.rst > index 2657a55c6f12..4b15ab671089 100644 > --- a/Documentation/process/coding-style.rst > +++ b/Documentation/process/coding-style.rst > @@ -319,6 +319,18 @@ If you are afraid to mix up your local variable names, > you have another > problem, which is called the function-growth-hormone-imbalance syndrome. > See chapter 6 (Functions). > > +For symbol names, avoid introducing new usage of the words 'slave' and > +'blacklist'. Recommended replacements for 'slave' are: 'secondary', > +'subordinate', 'replica', 'responder', 'follower', 'proxy', or > +'performer'. Recommended replacements for blacklist are: 'blocklist' or > +'denylist'. > + > +Exceptions for introducing new usage is to maintain a userspace ABI, or > +when updating code for an existing (as of 2020) hardware or protocol > +specification that mandates those terms. For new specifications consider > +translating specification usage of the terminology to the kernel coding > +standard where possible. See :ref:`process/inclusive-terminology.rst > +` for details. > > 5) Typedefs > --- > diff --git a/Documentation/process/inclusive-terminology.rst > b/Documentation/process/inclusive-terminology.rst > new file mode 100644 > index ..a8eb26690eb4 > --- /dev/null > +++ b/Documentation/process/inclusive-terminology.rst > @@ -0,0 +1,64 @@ > +.. _inclusiveterminology: > + > +Linux kernel inclusive terminology > +== > + > +The Linux kernel is a global software project, and in 2020 there was a > +global reckoning on race relations that caused many organizations to > +re-evaluate their policies and practices relative to the inclusion of > +people of African descent. This document describes why the 'Naming' > +section in :ref:`process/coding-style.rst ` recommends > +avoiding usage of 'slave' and 'blacklist' in new additions to the Linux > +kernel. > + > +On the triviality of replacing words > + > + > +The African slave trade was a brutal system of human misery deployed at > +global scale. Some word choice decisions in a modern software project > +does next to nothing to compensate for that legacy. So why put any > +effort into something so trivial in comparison? Because the goal is not > +to repair, or erase the past. The goal is to maximize availability and > +efficiency of the global developer community to participate in the Linux > +kernel development process. > + > +Word choice and developer efficiency > + > + > +Why does any software project go through the trouble of developing a > +document like :ref:`process/coding-style.rst `? It does so > +because a common coding style maximizes the efficiency of both > +maintainers and developers. Developers learn common design patterns and > +idiomatic expressions while maintainers can spot deviations from those > +norms. Even non-compliant whitespace is considered a leading indicator > +to deeper problems in a patchset. Coding style violations are known to > +take a maintainer "out of the zone" of reviewing code. Maintainers are > +also sensitive to word choice across specifications and often choose to > +deploy Linux terminology to replace non-idiomatic word-choice in a > +specification. > + > +Non-inclusive terminology has that same distracting effect which is why > +it is a style issue for Linux, it injures developer efficiency. > + > +Of course it is around this point someone jumps in with an etymological > +argument about why people should not be offended. Etymological arguments > +do not scale. The scope and pace of Linux to reach new developers > +exceeds the ability of historical terminology defenders to describe "no, > +not that connotation". The revelation of 2020 was that black voices were > +heard on a global scale and the Linux kernel project has done its small > +part to answer that call as it wants black voices, among all voices, in > +its developer community. I've been pondering about this statement for several weeks now, sleeping over it for far longer than I usual
Re: [Ksummit-discuss] [PATCH] CodingStyle: Inclusive Terminology
On Sun, Jul 12, 2020 at 9:26 PM Vinod Koul wrote: > > Hi Mauro, > > On 09-07-20, 13:11, Mauro Carvalho Chehab wrote: > > Em Mon, 06 Jul 2020 06:30:01 -0700 > > Joe Perches escreveu: > > > > > > $ git grep -i -w -P '\w*slave\w*' drivers | \ > > > cut -f1,2 -d/ | uniq -c | sort -rn | head -20 | cat -n > > > 1 5683 drivers/net > > > 2 2118 drivers/gpu > > > 3 1807 drivers/dma > > > 4 1389 drivers/i2c > > > 5 866 drivers/interconnect > > > 6 835 drivers/soundwire > > > 7 821 drivers/spi > > > 8 698 drivers/w1 > > > 9 508 drivers/media > > > 10 481 drivers/infiniband > > > 11 440 drivers/ata > > > 12 317 drivers/scsi > > > 13 267 drivers/fsi > > > 14 240 drivers/tty > > > 15 225 drivers/vme > > > 16 223 drivers/staging > > > 17 157 drivers/mmc > > > 18 155 drivers/usb > > > 19 141 drivers/video > > > 20 140 drivers/char > > > > It sounds that, as soon after this patch gets merged, the mailing lists > > will be flooded by lots of patches replacing such terms with something > > else :-( > > > > Doing a quick look at the media subsystem, it sounds that most terms > > come from I2C master/slave and DiSEqC terminology, as defined by their > > specs (and the others seem to be derived from some hardware vendor > > specific terminology). > > > > As they're all supported by the current specs, if one would want > > to replace them, it should first ensure that the supporting specs > > should be using a different terminology, as otherwise replacing > > them would just make harder for anyone trying to understand the > > code. > > I think waiting for specs may result in long delays, we all know how > 'fast' spec bodies work! > > Putting my soundwire maintainer hat, I see more than 1K uses of 'slave' > in the subsystem due to MIPI defined terms of SoundWire Master/Slave, so > I am planning to replace that and not wait for MIPI to update the spec. Sounds good. > A similar approach where we discuss with relevant stakeholder and arrive > at replacement terms and swap them would be great Right, just like any other coding-style cleanup, stage it the way that makes the most sense for the subsystem you maintain.
Re: [Ksummit-discuss] [PATCH] CodingStyle: Inclusive Terminology
Hi Mauro, On 09-07-20, 13:11, Mauro Carvalho Chehab wrote: > Em Mon, 06 Jul 2020 06:30:01 -0700 > Joe Perches escreveu: > > > > $ git grep -i -w -P '\w*slave\w*' drivers | \ > > cut -f1,2 -d/ | uniq -c | sort -rn | head -20 | cat -n > > 1 5683 drivers/net > > 2 2118 drivers/gpu > > 3 1807 drivers/dma > > 4 1389 drivers/i2c > > 5 866 drivers/interconnect > > 6 835 drivers/soundwire > > 7 821 drivers/spi > > 8 698 drivers/w1 > > 9 508 drivers/media > > 10 481 drivers/infiniband > > 11 440 drivers/ata > > 12 317 drivers/scsi > > 13 267 drivers/fsi > > 14 240 drivers/tty > > 15 225 drivers/vme > > 16 223 drivers/staging > > 17 157 drivers/mmc > > 18 155 drivers/usb > > 19 141 drivers/video > > 20 140 drivers/char > > It sounds that, as soon after this patch gets merged, the mailing lists > will be flooded by lots of patches replacing such terms with something > else :-( > > Doing a quick look at the media subsystem, it sounds that most terms > come from I2C master/slave and DiSEqC terminology, as defined by their > specs (and the others seem to be derived from some hardware vendor > specific terminology). > > As they're all supported by the current specs, if one would want > to replace them, it should first ensure that the supporting specs > should be using a different terminology, as otherwise replacing > them would just make harder for anyone trying to understand the > code. I think waiting for specs may result in long delays, we all know how 'fast' spec bodies work! Putting my soundwire maintainer hat, I see more than 1K uses of 'slave' in the subsystem due to MIPI defined terms of SoundWire Master/Slave, so I am planning to replace that and not wait for MIPI to update the spec. A similar approach where we discuss with relevant stakeholder and arrive at replacement terms and swap them would be great Thanks -- ~Vinod
Re: [Ksummit-discuss] [PATCH] CodingStyle: Inclusive Terminology
On Mon, Jul 6, 2020 at 9:30 PM Dan Williams wrote: > > On Sat, Jul 4, 2020 at 5:41 PM Kees Cook wrote: > > > > On Sat, Jul 04, 2020 at 01:02:51PM -0700, Dan Williams wrote: > > > Recent events have prompted a Linux position statement on inclusive > > > terminology. Given that Linux maintains a coding-style and its own > > > idiomatic set of terminology here is a proposal to answer the call to > > > replace non-inclusive terminology. > > > > > > Cc: Jonathan Corbet > > > Cc: Kees Cook > > > Signed-off-by: Chris Mason > > > Signed-off-by: Greg Kroah-Hartman > > > Signed-off-by: Dan Williams > > > > (nit: isn't this a Co-developed-by chain, not a SoB chain?) > > > > Acked-by: Kees Cook > > > > Comments below... > > > > > --- > > > Documentation/process/coding-style.rst | 12 > > > Documentation/process/inclusive-terminology.rst | 64 > > > +++ > > > Documentation/process/index.rst |1 > > > 3 files changed, 77 insertions(+) > > > create mode 100644 Documentation/process/inclusive-terminology.rst > > > > > > diff --git a/Documentation/process/coding-style.rst > > > b/Documentation/process/coding-style.rst > > > index 2657a55c6f12..4b15ab671089 100644 > > > --- a/Documentation/process/coding-style.rst > > > +++ b/Documentation/process/coding-style.rst > > > @@ -319,6 +319,18 @@ If you are afraid to mix up your local variable > > > names, you have another > > > problem, which is called the function-growth-hormone-imbalance syndrome. > > > See chapter 6 (Functions). > > > > > > +For symbol names, avoid introducing new usage of the words 'slave' and > > > +'blacklist'. Recommended replacements for 'slave' are: 'secondary', > > > +'subordinate', 'replica', 'responder', 'follower', 'proxy', or > > > +'performer'. Recommended replacements for blacklist are: 'blocklist' or > > > +'denylist'. > > > > Keeping "master" in a "master/slave" pairing (i.e. replacing only > > "slave") seems incomplete to me. If "master" is paired with "slave", it > > should be replaced too. Potential examples: 'primary', 'leader', > > 'principle', > > 'controller', 'sender', 'initial'. > > Yes, this matches Andy's feedback, will add. > > > Similarly, for "whitelist/blacklist", "whitelist" needs to replaced when > > "blacklist" has been. For example, seccomp documentation[1] uses > > "allow-list" and "deny-list". > > > > [1] https://man7.org/linux/man-pages/man2/seccomp.2.html > > Oh, good to know will make that change. Looks like that change already happened. And the new language is IMO not vastly better than the old language. I'll send a patch.
Re: [Tech-board-discuss] [Ksummit-discuss] [PATCH] CodingStyle: Inclusive Terminology
On Thu, 9 Jul 2020 17:13:51 +0100 Mark Brown wrote: > On Thu, Jul 09, 2020 at 10:01:18AM -0600, Shuah Khan wrote: > > On 7/9/20 4:43 AM, Mauro Carvalho Chehab wrote: > > > > For coherency, if "blacklist/whitelist" won't be used anymore, an > > > alternative to graylist should also be provided. > > > What is "graylist"? Does it mean in between allow/deny? > > Yes. Typically it's used in situations where you don't want to deny > something but might for example want to do extra checks to verify that > things are OK. The only time I use greylist is for postgrey, that when an email comes in, it will initially reject it, expecting the mail server to try again, and the second time it lets it through. This does stop a lot of spam, at the cost of waiting up to a few hours for email :-/ -- Steve
Re: [Tech-board-discuss] [Ksummit-discuss] [PATCH] CodingStyle: Inclusive Terminology
On Thu, Jul 09, 2020 at 10:01:18AM -0600, Shuah Khan wrote: > On 7/9/20 4:43 AM, Mauro Carvalho Chehab wrote: > > For coherency, if "blacklist/whitelist" won't be used anymore, an > > alternative to graylist should also be provided. > What is "graylist"? Does it mean in between allow/deny? Yes. Typically it's used in situations where you don't want to deny something but might for example want to do extra checks to verify that things are OK. signature.asc Description: PGP signature
Re: [Ksummit-discuss] [PATCH] CodingStyle: Inclusive Terminology
Em Mon, 06 Jul 2020 06:30:01 -0700 Joe Perches escreveu: > On Mon, 2020-07-06 at 09:04 -0400, Matthew Wilcox wrote: > > On Mon, Jul 6, 2020 at 8:59 AM Joe Perches wrote: > > > On Mon, 2020-07-06 at 08:51 -0400, Matthew Wilcox wrote: > > > > In terms of number of lines of code using the word, it's only seventh > > > > in drivers/: > > > > > > > > $ for i in drivers/*; do c=$(find $i -type f |xargs grep slave |wc > > > > -l); echo "$c $i"; done |sort -rn |head > > > > 5218 drivers/net > > > > 1341 drivers/dma > > > > 988 drivers/i2c > > > > 695 drivers/gpu > > > > 666 drivers/soundwire > > > > 665 drivers/spi > > > > 559 drivers/w1 > > > > 461 drivers/infiniband > > > > 389 drivers/media > > > > 301 drivers/scsi > > > > > > I get rather different and much lower numbers > > > > > > $ git grep -i -w slave drivers | \ > > > cut -f1,2 -d/ | uniq -c | sort -rn | head -20 | cat -n > > > > That's because you're using grep -w which excludes, for example, > > slave_configure in drivers/scsi. > > upper/lower case uses too... (anyway, there are a lot) > > $ git grep -i -w -P '\w*slave\w*' drivers | \ > cut -f1,2 -d/ | uniq -c | sort -rn | head -20 | cat -n > 1 5683 drivers/net > 2 2118 drivers/gpu > 3 1807 drivers/dma > 4 1389 drivers/i2c > 5866 drivers/interconnect > 6835 drivers/soundwire > 7821 drivers/spi > 8698 drivers/w1 > 9508 drivers/media > 10481 drivers/infiniband > 11440 drivers/ata > 12317 drivers/scsi > 13267 drivers/fsi > 14240 drivers/tty > 15225 drivers/vme > 16223 drivers/staging > 17157 drivers/mmc > 18155 drivers/usb > 19141 drivers/video > 20140 drivers/char It sounds that, as soon after this patch gets merged, the mailing lists will be flooded by lots of patches replacing such terms with something else :-( Doing a quick look at the media subsystem, it sounds that most terms come from I2C master/slave and DiSEqC terminology, as defined by their specs (and the others seem to be derived from some hardware vendor specific terminology). As they're all supported by the current specs, if one would want to replace them, it should first ensure that the supporting specs should be using a different terminology, as otherwise replacing them would just make harder for anyone trying to understand the code. Thanks, Mauro
Re: [Ksummit-discuss] [PATCH] CodingStyle: Inclusive Terminology
On Sat, Jul 04, 2020 at 01:02:51PM -0700, Dan Williams wrote: > Recent events have prompted a Linux position statement on inclusive > terminology. Given that Linux maintains a coding-style and its own > idiomatic set of terminology here is a proposal to answer the call to > replace non-inclusive terminology. > > Cc: Jonathan Corbet > Cc: Kees Cook > Signed-off-by: Chris Mason > Signed-off-by: Greg Kroah-Hartman > Signed-off-by: Dan Williams Acked-by: Daniel Vetter > --- > Documentation/process/coding-style.rst | 12 > Documentation/process/inclusive-terminology.rst | 64 > +++ > Documentation/process/index.rst |1 > 3 files changed, 77 insertions(+) > create mode 100644 Documentation/process/inclusive-terminology.rst > > diff --git a/Documentation/process/coding-style.rst > b/Documentation/process/coding-style.rst > index 2657a55c6f12..4b15ab671089 100644 > --- a/Documentation/process/coding-style.rst > +++ b/Documentation/process/coding-style.rst > @@ -319,6 +319,18 @@ If you are afraid to mix up your local variable names, > you have another > problem, which is called the function-growth-hormone-imbalance syndrome. > See chapter 6 (Functions). > > +For symbol names, avoid introducing new usage of the words 'slave' and > +'blacklist'. Recommended replacements for 'slave' are: 'secondary', > +'subordinate', 'replica', 'responder', 'follower', 'proxy', or > +'performer'. Recommended replacements for blacklist are: 'blocklist' or > +'denylist'. > + > +Exceptions for introducing new usage is to maintain a userspace ABI, or > +when updating code for an existing (as of 2020) hardware or protocol > +specification that mandates those terms. For new specifications consider > +translating specification usage of the terminology to the kernel coding > +standard where possible. See :ref:`process/inclusive-terminology.rst > +` for details. > > 5) Typedefs > --- > diff --git a/Documentation/process/inclusive-terminology.rst > b/Documentation/process/inclusive-terminology.rst > new file mode 100644 > index ..a8eb26690eb4 > --- /dev/null > +++ b/Documentation/process/inclusive-terminology.rst > @@ -0,0 +1,64 @@ > +.. _inclusiveterminology: > + > +Linux kernel inclusive terminology > +== > + > +The Linux kernel is a global software project, and in 2020 there was a > +global reckoning on race relations that caused many organizations to > +re-evaluate their policies and practices relative to the inclusion of > +people of African descent. This document describes why the 'Naming' > +section in :ref:`process/coding-style.rst ` recommends > +avoiding usage of 'slave' and 'blacklist' in new additions to the Linux > +kernel. > + > +On the triviality of replacing words > + > + > +The African slave trade was a brutal system of human misery deployed at > +global scale. Some word choice decisions in a modern software project > +does next to nothing to compensate for that legacy. So why put any > +effort into something so trivial in comparison? Because the goal is not > +to repair, or erase the past. The goal is to maximize availability and > +efficiency of the global developer community to participate in the Linux > +kernel development process. > + > +Word choice and developer efficiency > + > + > +Why does any software project go through the trouble of developing a > +document like :ref:`process/coding-style.rst `? It does so > +because a common coding style maximizes the efficiency of both > +maintainers and developers. Developers learn common design patterns and > +idiomatic expressions while maintainers can spot deviations from those > +norms. Even non-compliant whitespace is considered a leading indicator > +to deeper problems in a patchset. Coding style violations are known to > +take a maintainer "out of the zone" of reviewing code. Maintainers are > +also sensitive to word choice across specifications and often choose to > +deploy Linux terminology to replace non-idiomatic word-choice in a > +specification. > + > +Non-inclusive terminology has that same distracting effect which is why > +it is a style issue for Linux, it injures developer efficiency. > + > +Of course it is around this point someone jumps in with an etymological > +argument about why people should not be offended. Etymological arguments > +do not scale. The scope and pace of Linux to reach new developers > +exceeds the ability of historical terminology defenders to describe "no, > +not that connotation". The revelation of 2020 was that black voices were > +heard on a global scale and the Linux kernel project has done its small > +part to answer that call as it wants black voices, among all voices, in > +its developer community. > + > +Really, 'blacklist' too? > + > + > +While 'slave' has a direct connection to human suffering the etym
Re: Re: [Ksummit-discuss] [PATCH] CodingStyle: Inclusive Terminology
On Wed, 8 Jul 2020 00:12:03 -0700 Dan Williams wrote: > On Mon, Jul 6, 2020 at 11:56 PM SeongJae Park wrote: > > > > Hello, > > > > On Sat, 04 Jul 2020 13:02:51 -0700 Dan Williams > > wrote: > > > > > Recent events have prompted a Linux position statement on inclusive > > > terminology. Given that Linux maintains a coding-style and its own > > > idiomatic set of terminology here is a proposal to answer the call to > > > replace non-inclusive terminology. > > > > I'm glad to see this patch. > > > > > > > > Cc: Jonathan Corbet > > > Cc: Kees Cook > > > Signed-off-by: Chris Mason > > > Signed-off-by: Greg Kroah-Hartman > > > Signed-off-by: Dan Williams > > > > Acked-by: SeongJae Park > > > > > --- > > > Documentation/process/coding-style.rst | 12 > > > Documentation/process/inclusive-terminology.rst | 64 > > > +++ > > > Documentation/process/index.rst |1 > > > 3 files changed, 77 insertions(+) > > > create mode 100644 Documentation/process/inclusive-terminology.rst > > > > > > diff --git a/Documentation/process/coding-style.rst > > > b/Documentation/process/coding-style.rst > > > index 2657a55c6f12..4b15ab671089 100644 > > > --- a/Documentation/process/coding-style.rst > > > +++ b/Documentation/process/coding-style.rst > > > @@ -319,6 +319,18 @@ If you are afraid to mix up your local variable > > > names, you have another > > > problem, which is called the function-growth-hormone-imbalance syndrome. > > > See chapter 6 (Functions). > > > > > > +For symbol names, avoid introducing new usage of the words 'slave' and > > > +'blacklist'. Recommended replacements for 'slave' are: 'secondary', > > > +'subordinate', 'replica', 'responder', 'follower', 'proxy', or > > > +'performer'. Recommended replacements for blacklist are: 'blocklist' or > > > +'denylist'. > > > > I have submitted a couple of patches for automated encouragement of the the > > inclusive terms and those merged in the -next tree[1,2] now. Nonetheless, > > the > > version says only "please consider using 'denylist' and 'allowlist' instead > > of > > 'blacklist' and 'whitelist'" for now. I think we could add more terms in > > there > > based on this discussion. I could do that after this patch is merged, or > > you > > could do that yourself in the next spin of this patch. Please do whatever > > you > > feel comfort. > > > > [1] > > https://git.kernel.org/pub/scm/linux/kernel/git/next/linux-next.git/commit/?id=7d0bea01dec27195d95d929c1ee49a4a74dd6671 > > [2] > > https://git.kernel.org/pub/scm/linux/kernel/git/next/linux-next.git/commit/?id=95a94258ceb27052f00b7e51588a128d20bf05ed > > > > Thank you for stepping up to take this on, much appreciated. > > I think I'll leave it to you to fixup checkpatch after the final > version of this patch is merged. It may be as simple as "See section 4 > 'Naming' in coding-style for suggested replacements". Agreed, I will do that :) Thanks, SeongJae Park
Re: [Ksummit-discuss] [PATCH] CodingStyle: Inclusive Terminology
On Mon, Jul 6, 2020 at 11:56 PM SeongJae Park wrote: > > Hello, > > On Sat, 04 Jul 2020 13:02:51 -0700 Dan Williams > wrote: > > > Recent events have prompted a Linux position statement on inclusive > > terminology. Given that Linux maintains a coding-style and its own > > idiomatic set of terminology here is a proposal to answer the call to > > replace non-inclusive terminology. > > I'm glad to see this patch. > > > > > Cc: Jonathan Corbet > > Cc: Kees Cook > > Signed-off-by: Chris Mason > > Signed-off-by: Greg Kroah-Hartman > > Signed-off-by: Dan Williams > > Acked-by: SeongJae Park > > > --- > > Documentation/process/coding-style.rst | 12 > > Documentation/process/inclusive-terminology.rst | 64 > > +++ > > Documentation/process/index.rst |1 > > 3 files changed, 77 insertions(+) > > create mode 100644 Documentation/process/inclusive-terminology.rst > > > > diff --git a/Documentation/process/coding-style.rst > > b/Documentation/process/coding-style.rst > > index 2657a55c6f12..4b15ab671089 100644 > > --- a/Documentation/process/coding-style.rst > > +++ b/Documentation/process/coding-style.rst > > @@ -319,6 +319,18 @@ If you are afraid to mix up your local variable names, > > you have another > > problem, which is called the function-growth-hormone-imbalance syndrome. > > See chapter 6 (Functions). > > > > +For symbol names, avoid introducing new usage of the words 'slave' and > > +'blacklist'. Recommended replacements for 'slave' are: 'secondary', > > +'subordinate', 'replica', 'responder', 'follower', 'proxy', or > > +'performer'. Recommended replacements for blacklist are: 'blocklist' or > > +'denylist'. > > I have submitted a couple of patches for automated encouragement of the the > inclusive terms and those merged in the -next tree[1,2] now. Nonetheless, the > version says only "please consider using 'denylist' and 'allowlist' instead of > 'blacklist' and 'whitelist'" for now. I think we could add more terms in > there > based on this discussion. I could do that after this patch is merged, or you > could do that yourself in the next spin of this patch. Please do whatever you > feel comfort. > > [1] > https://git.kernel.org/pub/scm/linux/kernel/git/next/linux-next.git/commit/?id=7d0bea01dec27195d95d929c1ee49a4a74dd6671 > [2] > https://git.kernel.org/pub/scm/linux/kernel/git/next/linux-next.git/commit/?id=95a94258ceb27052f00b7e51588a128d20bf05ed > Thank you for stepping up to take this on, much appreciated. I think I'll leave it to you to fixup checkpatch after the final version of this patch is merged. It may be as simple as "See section 4 'Naming' in coding-style for suggested replacements".
Re: [Ksummit-discuss] [PATCH] CodingStyle: Inclusive Terminology
On Tue, Jul 07, 2020 at 01:54:23AM -0700, Kees Cook wrote: > On Tue, Jul 07, 2020 at 06:56:53AM +, Harrosh, Boaz wrote: > > Kees Cook wrote: > > > I have struggled with this as well. The parts of speech change, and my > > > grammar senses go weird. whitelist = adjective noun. allow-list = verb > > > noun. verbing the adj/noun combo feels okay, but verbing a verb/noun is > > > weird. > > > > > And just using "allowed" and "denied" doesn't impart whether it refers > > > to a _single_ instance or a _list_ of instances. > > > > > But that's all fine. The change is easy to do and is more descriptive > > > even if I can't find terms that don't collide with my internal grammar > > > checker. ;) > > > > But why. In English many times a verb when it comes before the noun means > > an adjective, or an adjective like, describing some traits of the noun. > > This is kind of my problem being a native English speaker: I can't > entirely describe _why_ a grammar construct feels wrong. :( > > > Example: > > I work - work is a verb here. > > I used the work bench. - Work is saying something about the type of bench, > > an adjective. Same as you would say "I used the green bench". > > Right, so the verb-noun being used as a noun is find, just as adj-noun > is. To me, "add it to the allow-list" is entirely sensible just like > "set it on the work-bench." It's the "verbing" of a noun that trips me > up. > > "I will whitelist the syscall" -- sounds correct to me (same for > "it is whitelisted" or "it is in whitelisting mode"). > > "I will allow-list the syscall" -- sounds wrong to me (same for > "it is allow-listed" or "it is in allow-listing mode"). I suspect it's at least partly because "allow" and "list" are both verbs -- in fact, "list" is the actual verb in "I will allow-list it", and "allow" is being used to modify the verb "list". But because "allow" is usually a verb, the sentence sounds like there are two verbs in there when there should only be one. I expect our ears will get trained to accept that sentence once you encounter "allowlist" often enough.
Re: [Tech-board-discuss] [Ksummit-discuss] [PATCH] CodingStyle: Inclusive Terminology
On Tue, 7 Jul 2020 01:54:23 -0700 Kees Cook wrote: > "I will whitelist the syscall" -- sounds correct to me (same for > "it is whitelisted" or "it is in whitelisting mode"). > > "I will allow-list the syscall" -- sounds wrong to me (same for > "it is allow-listed" or "it is in allow-listing mode"). That's because we can't just make "allow-list" a drop in replacement for "whitelist" as I too (native English speaker) find it awkward. But then we don't need to make it a drop in replacement. "I will whitelist the syscall" will become "I will add the syscall to the allow-list", which sounds perfectly fine, and even better than saying "I will add the syscall to the whitelist". -- Steve
Re: [Tech-board-discuss] [Ksummit-discuss] [PATCH] CodingStyle: Inclusive Terminology
On Tue, 7 Jul 2020 09:49:21 +0300 Mike Rapoport wrote: > > But that's all fine. The change is easy to do and is more descriptive > > even if I can't find terms that don't collide with my internal grammar > > checker. ;) > > How about yeslist and nolist? ;-) I was thinking good-list / bad-list. /me that has been doing a lot of git bisect lately... -- Steve
Re: [Ksummit-discuss] [PATCH] CodingStyle: Inclusive Terminology
On Tue, Jul 07, 2020 at 06:56:53AM +, Harrosh, Boaz wrote: > Kees Cook wrote: > > I have struggled with this as well. The parts of speech change, and my > > grammar senses go weird. whitelist = adjective noun. allow-list = verb > > noun. verbing the adj/noun combo feels okay, but verbing a verb/noun is > > weird. > But why. In English many times a verb when it comes before the noun means an > adjective, or an adjective like, describing some traits of the noun. I fear that if you are looking for logic or reason in English grammar you are on a path to disappointment. FWIW I share Kees' "that looks off" instinct with some of the usage of allow/deny. signature.asc Description: PGP signature
Re: [Ksummit-discuss] [PATCH] CodingStyle: Inclusive Terminology
On Tue, Jul 07, 2020 at 06:56:53AM +, Harrosh, Boaz wrote: > Kees Cook wrote: > > I have struggled with this as well. The parts of speech change, and my > > grammar senses go weird. whitelist = adjective noun. allow-list = verb > > noun. verbing the adj/noun combo feels okay, but verbing a verb/noun is > > weird. > > > And just using "allowed" and "denied" doesn't impart whether it refers > > to a _single_ instance or a _list_ of instances. > > > But that's all fine. The change is easy to do and is more descriptive > > even if I can't find terms that don't collide with my internal grammar > > checker. ;) > > But why. In English many times a verb when it comes before the noun means an > adjective, or an adjective like, describing some traits of the noun. This is kind of my problem being a native English speaker: I can't entirely describe _why_ a grammar construct feels wrong. :( > Example: > I work - work is a verb here. > I used the work bench. - Work is saying something about the type of bench, an > adjective. Same as you would say "I used the green bench". Right, so the verb-noun being used as a noun is find, just as adj-noun is. To me, "add it to the allow-list" is entirely sensible just like "set it on the work-bench." It's the "verbing" of a noun that trips me up. "I will whitelist the syscall" -- sounds correct to me (same for "it is whitelisted" or "it is in whitelisting mode"). "I will allow-list the syscall" -- sounds wrong to me (same for "it is allow-listed" or "it is in allow-listing mode"). Similarly, "I will work-bench" sounds wrong to me as does "it is work-benched" or "it is in work-benching mode". > I am not an English native at all but allow-list sounds totally English to > me. (I guess the very correct English way is "allowed-list" where the past > tense may convert the verb to a noun. but allow-list sounds very good to me > as well. Say work-list as opposed to vacation-list do you need to say > worked-list? I don't think so.) > > run mate, running mate. cutting board. these are all examples of verbs used > as adjectives. Are they not English? What am I missing I would like to learn? "it is in allowing-list mode" sounds even worse. :) But other things require the tense follow the merged verb: "It's already in the allowed-list" sounds fine, where "It's already in the whitelist" had no tense since it lacked a verb. I haven't been able to find an comfortable adjective that means "allow"; "allowable-list" is just long. But, as mentioned earlier -- I have just switched to more descriptive and less weird (to me) sentences. "It is set to deny by default" (instead of "it's a whitelist") or "It's already in the allowed-list". *shrug* -- Kees Cook
Re: [Ksummit-discuss] [PATCH] CodingStyle: Inclusive Terminology
On Sat, Jul 04, 2020 at 01:02:51PM -0700, Dan Williams wrote: > Recent events have prompted a Linux position statement on inclusive > terminology. Given that Linux maintains a coding-style and its own > idiomatic set of terminology here is a proposal to answer the call to > replace non-inclusive terminology. > > Cc: Jonathan Corbet > Cc: Kees Cook > Signed-off-by: Chris Mason > Signed-off-by: Greg Kroah-Hartman > Signed-off-by: Dan Williams > --- This is the right thing to do. Acked-by: Christian Brauner (Imho, I agree with Andy and the historical bits could probably be moved into the changelog.) > Documentation/process/coding-style.rst | 12 > Documentation/process/inclusive-terminology.rst | 64 > +++ > Documentation/process/index.rst |1 > 3 files changed, 77 insertions(+) > create mode 100644 Documentation/process/inclusive-terminology.rst > > diff --git a/Documentation/process/coding-style.rst > b/Documentation/process/coding-style.rst > index 2657a55c6f12..4b15ab671089 100644 > --- a/Documentation/process/coding-style.rst > +++ b/Documentation/process/coding-style.rst > @@ -319,6 +319,18 @@ If you are afraid to mix up your local variable names, > you have another > problem, which is called the function-growth-hormone-imbalance syndrome. > See chapter 6 (Functions). > > +For symbol names, avoid introducing new usage of the words 'slave' and > +'blacklist'. Recommended replacements for 'slave' are: 'secondary', > +'subordinate', 'replica', 'responder', 'follower', 'proxy', or > +'performer'. Recommended replacements for blacklist are: 'blocklist' or > +'denylist'. > + > +Exceptions for introducing new usage is to maintain a userspace ABI, or > +when updating code for an existing (as of 2020) hardware or protocol > +specification that mandates those terms. For new specifications consider > +translating specification usage of the terminology to the kernel coding > +standard where possible. See :ref:`process/inclusive-terminology.rst > +` for details. > > 5) Typedefs > --- > diff --git a/Documentation/process/inclusive-terminology.rst > b/Documentation/process/inclusive-terminology.rst > new file mode 100644 > index ..a8eb26690eb4 > --- /dev/null > +++ b/Documentation/process/inclusive-terminology.rst > @@ -0,0 +1,64 @@ > +.. _inclusiveterminology: > + > +Linux kernel inclusive terminology > +== > + > +The Linux kernel is a global software project, and in 2020 there was a > +global reckoning on race relations that caused many organizations to > +re-evaluate their policies and practices relative to the inclusion of > +people of African descent. This document describes why the 'Naming' > +section in :ref:`process/coding-style.rst ` recommends > +avoiding usage of 'slave' and 'blacklist' in new additions to the Linux > +kernel. > + > +On the triviality of replacing words > + > + > +The African slave trade was a brutal system of human misery deployed at > +global scale. Some word choice decisions in a modern software project > +does next to nothing to compensate for that legacy. So why put any > +effort into something so trivial in comparison? Because the goal is not > +to repair, or erase the past. The goal is to maximize availability and > +efficiency of the global developer community to participate in the Linux > +kernel development process. > + > +Word choice and developer efficiency > + > + > +Why does any software project go through the trouble of developing a > +document like :ref:`process/coding-style.rst `? It does so > +because a common coding style maximizes the efficiency of both > +maintainers and developers. Developers learn common design patterns and > +idiomatic expressions while maintainers can spot deviations from those > +norms. Even non-compliant whitespace is considered a leading indicator > +to deeper problems in a patchset. Coding style violations are known to > +take a maintainer "out of the zone" of reviewing code. Maintainers are > +also sensitive to word choice across specifications and often choose to > +deploy Linux terminology to replace non-idiomatic word-choice in a > +specification. > + > +Non-inclusive terminology has that same distracting effect which is why > +it is a style issue for Linux, it injures developer efficiency. > + > +Of course it is around this point someone jumps in with an etymological > +argument about why people should not be offended. Etymological arguments > +do not scale. The scope and pace of Linux to reach new developers > +exceeds the ability of historical terminology defenders to describe "no, > +not that connotation". The revelation of 2020 was that black voices were > +heard on a global scale and the Linux kernel project has done its small > +part to answer that call as it wants black voices, among all voices, in > +its developer community.
Re: [Ksummit-discuss] [PATCH] CodingStyle: Inclusive Terminology
Kees Cook wrote: > I have struggled with this as well. The parts of speech change, and my > grammar senses go weird. whitelist = adjective noun. allow-list = verb > noun. verbing the adj/noun combo feels okay, but verbing a verb/noun is > weird. > And just using "allowed" and "denied" doesn't impart whether it refers > to a _single_ instance or a _list_ of instances. > But that's all fine. The change is easy to do and is more descriptive > even if I can't find terms that don't collide with my internal grammar > checker. ;) But why. In English many times a verb when it comes before the noun means an adjective, or an adjective like, describing some traits of the noun. Example: I work - work is a verb here. I used the work bench. - Work is saying something about the type of bench, an adjective. Same as you would say "I used the green bench". I am not an English native at all but allow-list sounds totally English to me. (I guess the very correct English way is "allowed-list" where the past tense may convert the verb to a noun. but allow-list sounds very good to me as well. Say work-list as opposed to vacation-list do you need to say worked-list? I don't think so.) run mate, running mate. cutting board. these are all examples of verbs used as adjectives. Are they not English? What am I missing I would like to learn? Thanks Boaz
Re: [Ksummit-discuss] [PATCH] CodingStyle: Inclusive Terminology
Hello, On Sat, 04 Jul 2020 13:02:51 -0700 Dan Williams wrote: > Recent events have prompted a Linux position statement on inclusive > terminology. Given that Linux maintains a coding-style and its own > idiomatic set of terminology here is a proposal to answer the call to > replace non-inclusive terminology. I'm glad to see this patch. > > Cc: Jonathan Corbet > Cc: Kees Cook > Signed-off-by: Chris Mason > Signed-off-by: Greg Kroah-Hartman > Signed-off-by: Dan Williams Acked-by: SeongJae Park > --- > Documentation/process/coding-style.rst | 12 > Documentation/process/inclusive-terminology.rst | 64 > +++ > Documentation/process/index.rst |1 > 3 files changed, 77 insertions(+) > create mode 100644 Documentation/process/inclusive-terminology.rst > > diff --git a/Documentation/process/coding-style.rst > b/Documentation/process/coding-style.rst > index 2657a55c6f12..4b15ab671089 100644 > --- a/Documentation/process/coding-style.rst > +++ b/Documentation/process/coding-style.rst > @@ -319,6 +319,18 @@ If you are afraid to mix up your local variable names, > you have another > problem, which is called the function-growth-hormone-imbalance syndrome. > See chapter 6 (Functions). > > +For symbol names, avoid introducing new usage of the words 'slave' and > +'blacklist'. Recommended replacements for 'slave' are: 'secondary', > +'subordinate', 'replica', 'responder', 'follower', 'proxy', or > +'performer'. Recommended replacements for blacklist are: 'blocklist' or > +'denylist'. I have submitted a couple of patches for automated encouragement of the the inclusive terms and those merged in the -next tree[1,2] now. Nonetheless, the version says only "please consider using 'denylist' and 'allowlist' instead of 'blacklist' and 'whitelist'" for now. I think we could add more terms in there based on this discussion. I could do that after this patch is merged, or you could do that yourself in the next spin of this patch. Please do whatever you feel comfort. [1] https://git.kernel.org/pub/scm/linux/kernel/git/next/linux-next.git/commit/?id=7d0bea01dec27195d95d929c1ee49a4a74dd6671 [2] https://git.kernel.org/pub/scm/linux/kernel/git/next/linux-next.git/commit/?id=95a94258ceb27052f00b7e51588a128d20bf05ed Thanks, SeongJae Park
Re: [Ksummit-discuss] [PATCH] CodingStyle: Inclusive Terminology
On Mon, Jul 06, 2020 at 10:56:17PM -0700, Kees Cook wrote: > On Mon, Jul 06, 2020 at 09:29:46AM -0700, Andy Lutomirski wrote: > > Is most contexts where 'whitelist' or 'blacklist' might be used, a > > descriptive phrase could be used instead. For example, a seccomp > > filter could have a 'list of allowed syscalls' or a 'list of > > disallowed syscalls', and just lists could be the 'allowed' or > > 'accepted' lists and the 'disallowed', 'rejected', or 'blocked' lists. > > If a single word replacement for 'whitelist' or 'blacklist' is needed, > > 'allowlist', 'blocklist', or 'denylist' could be used. > > Yup. See: > https://lore.kernel.org/lkml/202007041703.51F4059CA@keescook/ > specifically the terminology for seccomp is already "allow-list" and > "deny-list": > https://github.com/mkerrisk/man-pages/commit/462ce23d491904a0b46252dc97c8cb42391c093e > (last year) > https://github.com/seccomp/libseccomp/commit/0e762521d604612bb4dca8867d4a428a5e6cae54 > (last month) > > > Second, I realize that I grew up thinking that 'whitelist' and > > 'blacklist' are the common terms for lists of things to be accepted > > and rejected and that this biases my perception of what sounds good, > > but writing a seccomp "denylist" or "blocklist" doesn't seem to roll > > off the tongue. Perhaps this language would be better: > > I have struggled with this as well. The parts of speech change, and my > grammar senses go weird. whitelist = adjective noun. allow-list = verb > noun. verbing the adj/noun combo feels okay, but verbing a verb/noun is > weird. > > And just using "allowed" and "denied" doesn't impart whether it refers > to a _single_ instance or a _list_ of instances. > > But that's all fine. The change is easy to do and is more descriptive > even if I can't find terms that don't collide with my internal grammar > checker. ;) How about yeslist and nolist? ;-) > -- > Kees Cook > ___ > Ksummit-discuss mailing list > ksummit-disc...@lists.linuxfoundation.org > https://lists.linuxfoundation.org/mailman/listinfo/ksummit-discuss -- Sincerely yours, Mike.
Re: [Ksummit-discuss] [PATCH] CodingStyle: Inclusive Terminology
On Mon, Jul 06, 2020 at 09:29:46AM -0700, Andy Lutomirski wrote: > Is most contexts where 'whitelist' or 'blacklist' might be used, a > descriptive phrase could be used instead. For example, a seccomp > filter could have a 'list of allowed syscalls' or a 'list of > disallowed syscalls', and just lists could be the 'allowed' or > 'accepted' lists and the 'disallowed', 'rejected', or 'blocked' lists. > If a single word replacement for 'whitelist' or 'blacklist' is needed, > 'allowlist', 'blocklist', or 'denylist' could be used. Yup. See: https://lore.kernel.org/lkml/202007041703.51F4059CA@keescook/ specifically the terminology for seccomp is already "allow-list" and "deny-list": https://github.com/mkerrisk/man-pages/commit/462ce23d491904a0b46252dc97c8cb42391c093e (last year) https://github.com/seccomp/libseccomp/commit/0e762521d604612bb4dca8867d4a428a5e6cae54 (last month) > Second, I realize that I grew up thinking that 'whitelist' and > 'blacklist' are the common terms for lists of things to be accepted > and rejected and that this biases my perception of what sounds good, > but writing a seccomp "denylist" or "blocklist" doesn't seem to roll > off the tongue. Perhaps this language would be better: I have struggled with this as well. The parts of speech change, and my grammar senses go weird. whitelist = adjective noun. allow-list = verb noun. verbing the adj/noun combo feels okay, but verbing a verb/noun is weird. And just using "allowed" and "denied" doesn't impart whether it refers to a _single_ instance or a _list_ of instances. But that's all fine. The change is easy to do and is more descriptive even if I can't find terms that don't collide with my internal grammar checker. ;) -- Kees Cook
Re: [Ksummit-discuss] [PATCH] CodingStyle: Inclusive Terminology
On Mon, Jul 6, 2020 at 9:07 AM Mike Rapoport wrote: > > Hi Chris, > > On Mon, Jul 06, 2020 at 12:45:34PM +, Chris Mason via Ksummit-discuss > wrote: > > On 5 Jul 2020, at 0:55, Willy Tarreau wrote: > > > > > On Sat, Jul 04, 2020 at 01:02:51PM -0700, Dan Williams wrote: > > >> +Non-inclusive terminology has that same distracting effect which is > > >> why > > >> +it is a style issue for Linux, it injures developer efficiency. > > > > > > I'm personally thinking that for a non-native speaker it's already > > > difficult to find the best term to describe something, but having to > > > apply an extra level of filtering on the found words to figure whether > > > they are allowed by the language police is even more difficult. > > > > Since our discussions are public, we’ve always had to deal with > > comments from people outside the community on a range of topics. But > > inside the kernel, it’s just a group of developers trying to help each > > other produce the best quality of code. We’ve got a long history > > together and in general I think we’re pretty good at assuming good > > intent. > > I don't think anybody doubts your intentions. But they say, the road to > hell is paved with good intentions. > > I had a "privilege" to live in the USSR and back there Newspeak was not a > fiction but a reality. > > And despite the good intent, I have a really strong feeling that this > could be a step in a wrong direction... I've experienced some professional training classes for visiting other countries and they tell you helpful things like "avoid making jokes about X" or "Y topic is sensitive". It's not about censoring it's more about how to keep discussion focused on the job at hand. So I'm hoping this is more of the mundane advice of "what's the best way to communicate my point efficiently to the widest possible audience" and not a "step in a wrong direction"... time will tell.
Re: [Ksummit-discuss] [PATCH] CodingStyle: Inclusive Terminology
On Mon, Jul 6, 2020 at 9:30 AM Andy Lutomirski wrote: > > On Sat, Jul 4, 2020 at 1:19 PM Dan Williams wrote: > > > > Recent events have prompted a Linux position statement on inclusive > > terminology. Given that Linux maintains a coding-style and its own > > idiomatic set of terminology here is a proposal to answer the call to > > replace non-inclusive terminology. > > > > Cc: Jonathan Corbet > > Cc: Kees Cook > > Signed-off-by: Chris Mason > > Signed-off-by: Greg Kroah-Hartman > > Signed-off-by: Dan Williams > > --- > > Documentation/process/coding-style.rst | 12 > > Documentation/process/inclusive-terminology.rst | 64 > > +++ > > Documentation/process/index.rst |1 > > 3 files changed, 77 insertions(+) > > create mode 100644 Documentation/process/inclusive-terminology.rst > > > > diff --git a/Documentation/process/coding-style.rst > > b/Documentation/process/coding-style.rst > > index 2657a55c6f12..4b15ab671089 100644 > > --- a/Documentation/process/coding-style.rst > > +++ b/Documentation/process/coding-style.rst > > @@ -319,6 +319,18 @@ If you are afraid to mix up your local variable names, > > you have another > > problem, which is called the function-growth-hormone-imbalance syndrome. > > See chapter 6 (Functions). > > > > +For symbol names, avoid introducing new usage of the words 'slave' and > > +'blacklist' > > Can you put whitelist in the list, too? Yes, will do. I had left it out mistakenly thinking it would help focus the discussion, but the replacements don't make sense without including the replacements for whitelist. > > >. Recommended replacements for 'slave' are: 'secondary', > > +'subordinate', 'replica', 'responder', 'follower', 'proxy', or > > +'performer'. > > Should 'target' be in this list? Yes. > Should there be some mention of "master" to go along with "slave"? > This could be complicated -- as has been noted in this thread, the > word "master" has quite a few meanings, several of which are not > related to slavery or to any form of control, and that the meanings > associated with "master" and its cognates in other languages vary. Yes, I'll at least expand this with the paired terminology for each of the replacements of 'slave'. > > > Recommended replacements for blacklist are: 'blocklist' or > > +'denylist'. > > As someone who has written seccomp code and described the result as a > "whitelist" or "blacklist" in the past, I have a couple of comments. > > First, shouldn't whitelist be in the list? I find it surprising to > put 'blacklist' in the blocklist but to omit whitelist. > > Second, I realize that I grew up thinking that 'whitelist' and > 'blacklist' are the common terms for lists of things to be accepted > and rejected and that this biases my perception of what sounds good, > but writing a seccomp "denylist" or "blocklist" doesn't seem to roll > off the tongue. Perhaps this language would be better: > > Is most contexts where 'whitelist' or 'blacklist' might be used, a > descriptive phrase could be used instead. For example, a seccomp > filter could have a 'list of allowed syscalls' or a 'list of > disallowed syscalls', and just lists could be the 'allowed' or > 'accepted' lists and the 'disallowed', 'rejected', or 'blocked' lists. > If a single word replacement for 'whitelist' or 'blacklist' is needed, > 'allowlist', 'blocklist', or 'denylist' could be used. That makes practical sense to me. Now that I look at this I think the recommendation for the shorthand replacement should only be one style option, lets say "blocklist/passlist" because it's not as amenable to context sensitive replacements as "slave" and benefits from a standard single shorthand. > > > > @@ -0,0 +1,64 @@ > > +.. _inclusiveterminology: > > + > > +Linux kernel inclusive terminology > > +== > > + > > +The Linux kernel is a global software project, and in 2020 there was a > > +global reckoning on race relations that caused many organizations to > > +re-evaluate their policies and practices relative to the inclusion of > > +people of African descent. This document describes why the 'Naming' > > +section in :ref:`process/coding-style.rst ` recommends > > +avoiding usage of 'slave' and 'blacklist' in new additions to the Linux > > +kernel. > > + > > +On the triviality of replacing words > > + > > + > > +The African slave trade was a brutal system of human misery deployed at > > +global scale. Some word choice decisions in a modern software project > > +does next to nothing to compensate for that legacy. So why put any > > +effort into something so trivial in comparison? Because the goal is not > > +to repair, or erase the past. The goal is to maximize availability and > > +efficiency of the global developer community to participate in the Linux > > +kernel development process. > > Should this type of historical note be in the document or in the changelog?
Re: [Ksummit-discuss] [PATCH] CodingStyle: Inclusive Terminology
On Sat, Jul 4, 2020 at 1:19 PM Dan Williams wrote: > > Recent events have prompted a Linux position statement on inclusive > terminology. Given that Linux maintains a coding-style and its own > idiomatic set of terminology here is a proposal to answer the call to > replace non-inclusive terminology. > > Cc: Jonathan Corbet > Cc: Kees Cook > Signed-off-by: Chris Mason > Signed-off-by: Greg Kroah-Hartman > Signed-off-by: Dan Williams > --- > Documentation/process/coding-style.rst | 12 > Documentation/process/inclusive-terminology.rst | 64 > +++ > Documentation/process/index.rst |1 > 3 files changed, 77 insertions(+) > create mode 100644 Documentation/process/inclusive-terminology.rst > > diff --git a/Documentation/process/coding-style.rst > b/Documentation/process/coding-style.rst > index 2657a55c6f12..4b15ab671089 100644 > --- a/Documentation/process/coding-style.rst > +++ b/Documentation/process/coding-style.rst > @@ -319,6 +319,18 @@ If you are afraid to mix up your local variable names, > you have another > problem, which is called the function-growth-hormone-imbalance syndrome. > See chapter 6 (Functions). > > +For symbol names, avoid introducing new usage of the words 'slave' and > +'blacklist' Can you put whitelist in the list, too? >. Recommended replacements for 'slave' are: 'secondary', > +'subordinate', 'replica', 'responder', 'follower', 'proxy', or > +'performer'. Should 'target' be in this list? Should there be some mention of "master" to go along with "slave"? This could be complicated -- as has been noted in this thread, the word "master" has quite a few meanings, several of which are not related to slavery or to any form of control, and that the meanings associated with "master" and its cognates in other languages vary. > Recommended replacements for blacklist are: 'blocklist' or > +'denylist'. As someone who has written seccomp code and described the result as a "whitelist" or "blacklist" in the past, I have a couple of comments. First, shouldn't whitelist be in the list? I find it surprising to put 'blacklist' in the blocklist but to omit whitelist. Second, I realize that I grew up thinking that 'whitelist' and 'blacklist' are the common terms for lists of things to be accepted and rejected and that this biases my perception of what sounds good, but writing a seccomp "denylist" or "blocklist" doesn't seem to roll off the tongue. Perhaps this language would be better: Is most contexts where 'whitelist' or 'blacklist' might be used, a descriptive phrase could be used instead. For example, a seccomp filter could have a 'list of allowed syscalls' or a 'list of disallowed syscalls', and just lists could be the 'allowed' or 'accepted' lists and the 'disallowed', 'rejected', or 'blocked' lists. If a single word replacement for 'whitelist' or 'blacklist' is needed, 'allowlist', 'blocklist', or 'denylist' could be used. > @@ -0,0 +1,64 @@ > +.. _inclusiveterminology: > + > +Linux kernel inclusive terminology > +== > + > +The Linux kernel is a global software project, and in 2020 there was a > +global reckoning on race relations that caused many organizations to > +re-evaluate their policies and practices relative to the inclusion of > +people of African descent. This document describes why the 'Naming' > +section in :ref:`process/coding-style.rst ` recommends > +avoiding usage of 'slave' and 'blacklist' in new additions to the Linux > +kernel. > + > +On the triviality of replacing words > + > + > +The African slave trade was a brutal system of human misery deployed at > +global scale. Some word choice decisions in a modern software project > +does next to nothing to compensate for that legacy. So why put any > +effort into something so trivial in comparison? Because the goal is not > +to repair, or erase the past. The goal is to maximize availability and > +efficiency of the global developer community to participate in the Linux > +kernel development process. Should this type of historical note be in the document or in the changelog? Suppose that we put it in this document and then, in two years, someone notices that the very first bit of text in your changelog that diff helpfully quoted for you is also mildly offensive to certain groups Now we could end up with: ... in 2020 there was a global reckoning ... ... in 2022, people noticed that comparing peoples' opinions on variable names to medical conditions could be seen as inappropriate ... etc. And now this document ends up with a lot of history and also a lot of content, and the history part starts to resemble the now-frowned-upon lists of copyrights and changes that clutter the tops of various kernel C files. I suppose that changing this could be deferred until such time as it might be an actual problem, but perhaps this should go in the changelog instead.
Re: [Ksummit-discuss] [PATCH] CodingStyle: Inclusive Terminology
Hi Chris, On Mon, Jul 06, 2020 at 12:45:34PM +, Chris Mason via Ksummit-discuss wrote: > On 5 Jul 2020, at 0:55, Willy Tarreau wrote: > > > On Sat, Jul 04, 2020 at 01:02:51PM -0700, Dan Williams wrote: > >> +Non-inclusive terminology has that same distracting effect which is > >> why > >> +it is a style issue for Linux, it injures developer efficiency. > > > > I'm personally thinking that for a non-native speaker it's already > > difficult to find the best term to describe something, but having to > > apply an extra level of filtering on the found words to figure whether > > they are allowed by the language police is even more difficult. > > Since our discussions are public, we’ve always had to deal with > comments from people outside the community on a range of topics. But > inside the kernel, it’s just a group of developers trying to help each > other produce the best quality of code. We’ve got a long history > together and in general I think we’re pretty good at assuming good > intent. I don't think anybody doubts your intentions. But they say, the road to hell is paved with good intentions. I had a "privilege" to live in the USSR and back there Newspeak was not a fiction but a reality. And despite the good intent, I have a really strong feeling that this could be a step in a wrong direction... > > *This* > > injures developers efficiency. What could improve developers > > efficiency > > is to take care of removing *all* idiomatic or cultural words then. > > For > > example I've been participating to projects using the term > > "blueprint", > > I didn't understand what that meant. It was once explained to me and > > given that it had no logical reason for being called this way, I now > > forgot. If we follow your reasoning, Such words should be banned for > > exactly the same reasons. Same for colors that probably don't mean > > anything to those born blind. > > > > For example if in my local culture we eat tomatoes at starters and > > apples for dessert, it could be convenient for me to use "tomato" and > > "apple" as list elements to name the pointers leading to the beginning > > and the end of the list, and it might sound obvious to many people, > > but > > not at all for many others. > > > > Maybe instead of providing an explicit list of a few words it should > > simply say that terms that take their roots in the non-technical world > > and whose meaning can only be understood based on history or local > > culture ought to be avoided, because *that* actually is the real > > root cause of the problem you're trying to address. > > I’d definitely agree that it’s a good goal to keep out non-technical > terms. Even though we already try, every subsystem has its own set of > patterns that reflect the most frequent contributors. > > -chris > ___ > Ksummit-discuss mailing list > ksummit-disc...@lists.linuxfoundation.org > https://lists.linuxfoundation.org/mailman/listinfo/ksummit-discuss -- Sincerely yours, Mike.
Re: [Ksummit-discuss] [PATCH] CodingStyle: Inclusive Terminology
On 6 Jul 2020, at 10:06, Laurent Pinchart wrote: Hi Chris, On Mon, Jul 06, 2020 at 12:45:34PM +, Chris Mason via Ksummit-discuss wrote: On 5 Jul 2020, at 0:55, Willy Tarreau wrote: Maybe instead of providing an explicit list of a few words it should simply say that terms that take their roots in the non-technical world and whose meaning can only be understood based on history or local culture ought to be avoided, because *that* actually is the real root cause of the problem you're trying to address. I’d definitely agree that it’s a good goal to keep out non-technical terms. Even though we already try, every subsystem has its own set of patterns that reflect the most frequent contributors. That's an interesting point, because to me, it's the exact opposite. One of the intellectual rewards I find in working with the kernel is that our community is international and multicultural, allowing me to learn about other cultures. Aiming for the lowest common denominator seems to me to be closer to erasing cultural differences than including them. I hadn’t thought of it from this angle, but I do agree with you. I think the cultural side comes through more in discussions and in-person conferences than it does from the code itself. I do try to avoid local idioms or culture references unless I’m explaining them as part of a discussion or a personal story, mostly because I’ve gotten feedback from coworkers who had a hard time following my bad (ok, terrible) jokes or sarcasm. One internal example is commands that take —clowntown as an argument. It’s pretty therapeutic to type when you’re grumpy about tooling, but a lot of people probably have to look it up before it makes sense. -chris
Re: [Ksummit-discuss] [PATCH] CodingStyle: Inclusive Terminology
Hi Chris, On Mon, Jul 06, 2020 at 12:45:34PM +, Chris Mason via Ksummit-discuss wrote: > On 5 Jul 2020, at 0:55, Willy Tarreau wrote: > > On Sat, Jul 04, 2020 at 01:02:51PM -0700, Dan Williams wrote: > >> +Non-inclusive terminology has that same distracting effect which is why > >> +it is a style issue for Linux, it injures developer efficiency. > > > > I'm personally thinking that for a non-native speaker it's already > > difficult to find the best term to describe something, but having to > > apply an extra level of filtering on the found words to figure whether > > they are allowed by the language police is even more difficult. > > Since our discussions are public, we’ve always had to deal with > comments from people outside the community on a range of topics. But > inside the kernel, it’s just a group of developers trying to help each > other produce the best quality of code. We’ve got a long history > together and in general I think we’re pretty good at assuming good > intent. > > > *This* injures developers efficiency. What could improve developers > > efficiency > > is to take care of removing *all* idiomatic or cultural words then. For > > example I've been participating to projects using the term "blueprint", > > I didn't understand what that meant. It was once explained to me and > > given that it had no logical reason for being called this way, I now > > forgot. If we follow your reasoning, Such words should be banned for > > exactly the same reasons. Same for colors that probably don't mean > > anything to those born blind. > > > > For example if in my local culture we eat tomatoes at starters and > > apples for dessert, it could be convenient for me to use "tomato" and > > "apple" as list elements to name the pointers leading to the beginning > > and the end of the list, and it might sound obvious to many people, but > > not at all for many others. > > > > Maybe instead of providing an explicit list of a few words it should > > simply say that terms that take their roots in the non-technical world > > and whose meaning can only be understood based on history or local > > culture ought to be avoided, because *that* actually is the real > > root cause of the problem you're trying to address. > > I’d definitely agree that it’s a good goal to keep out non-technical > terms. Even though we already try, every subsystem has its own set of > patterns that reflect the most frequent contributors. That's an interesting point, because to me, it's the exact opposite. One of the intellectual rewards I find in working with the kernel is that our community is international and multicultural, allowing me to learn about other cultures. Aiming for the lowest common denominator seems to me to be closer to erasing cultural differences than including them. -- Regards, Laurent Pinchart
Re: [Ksummit-discuss] [PATCH] CodingStyle: Inclusive Terminology
On Mon, 2020-07-06 at 09:04 -0400, Matthew Wilcox wrote: > On Mon, Jul 6, 2020 at 8:59 AM Joe Perches wrote: > > On Mon, 2020-07-06 at 08:51 -0400, Matthew Wilcox wrote: > > > In terms of number of lines of code using the word, it's only seventh > > > in drivers/: > > > > > > $ for i in drivers/*; do c=$(find $i -type f |xargs grep slave |wc > > > -l); echo "$c $i"; done |sort -rn |head > > > 5218 drivers/net > > > 1341 drivers/dma > > > 988 drivers/i2c > > > 695 drivers/gpu > > > 666 drivers/soundwire > > > 665 drivers/spi > > > 559 drivers/w1 > > > 461 drivers/infiniband > > > 389 drivers/media > > > 301 drivers/scsi > > > > I get rather different and much lower numbers > > > > $ git grep -i -w slave drivers | \ > > cut -f1,2 -d/ | uniq -c | sort -rn | head -20 | cat -n > > That's because you're using grep -w which excludes, for example, > slave_configure in drivers/scsi. upper/lower case uses too... (anyway, there are a lot) $ git grep -i -w -P '\w*slave\w*' drivers | \ cut -f1,2 -d/ | uniq -c | sort -rn | head -20 | cat -n 1 5683 drivers/net 2 2118 drivers/gpu 3 1807 drivers/dma 4 1389 drivers/i2c 5 866 drivers/interconnect 6 835 drivers/soundwire 7 821 drivers/spi 8 698 drivers/w1 9 508 drivers/media 10 481 drivers/infiniband 11 440 drivers/ata 12 317 drivers/scsi 13 267 drivers/fsi 14 240 drivers/tty 15 225 drivers/vme 16 223 drivers/staging 17 157 drivers/mmc 18 155 drivers/usb 19 141 drivers/video 20 140 drivers/char
Re: [Ksummit-discuss] [PATCH] CodingStyle: Inclusive Terminology
On Mon, Jul 6, 2020 at 8:59 AM Joe Perches wrote: > On Mon, 2020-07-06 at 08:51 -0400, Matthew Wilcox wrote: > > In terms of number of lines of code using the word, it's only seventh > > in drivers/: > > > > $ for i in drivers/*; do c=$(find $i -type f |xargs grep slave |wc > > -l); echo "$c $i"; done |sort -rn |head > > 5218 drivers/net > > 1341 drivers/dma > > 988 drivers/i2c > > 695 drivers/gpu > > 666 drivers/soundwire > > 665 drivers/spi > > 559 drivers/w1 > > 461 drivers/infiniband > > 389 drivers/media > > 301 drivers/scsi > > I get rather different and much lower numbers > > $ git grep -i -w slave drivers | \ > cut -f1,2 -d/ | uniq -c | sort -rn | head -20 | cat -n That's because you're using grep -w which excludes, for example, slave_configure in drivers/scsi.
Re: [Ksummit-discuss] [PATCH] CodingStyle: Inclusive Terminology
On Mon, 2020-07-06 at 08:51 -0400, Matthew Wilcox wrote: [] > In terms of number of lines of code using the word, it's only seventh > in drivers/: > > $ for i in drivers/*; do c=$(find $i -type f |xargs grep slave |wc > -l); echo "$c $i"; done |sort -rn |head > 5218 drivers/net > 1341 drivers/dma > 988 drivers/i2c > 695 drivers/gpu > 666 drivers/soundwire > 665 drivers/spi > 559 drivers/w1 > 461 drivers/infiniband > 389 drivers/media > 301 drivers/scsi I get rather different and much lower numbers $ git grep -i -w slave drivers | \ cut -f1,2 -d/ | uniq -c | sort -rn | head -20 | cat -n 1 3091 drivers/net 2 654 drivers/i2c 3 595 drivers/soundwire 4 483 drivers/dma 5 284 drivers/infiniband 6 269 drivers/gpu 7 198 drivers/media 8 192 drivers/fsi 9 174 drivers/spi 10 131 drivers/ata 11 111 drivers/w1 12 110 drivers/staging 13 89 drivers/iio 14 71 drivers/usb 15 60 drivers/mfd 16 53 drivers/soc 17 52 drivers/tty 18 32 drivers/vme 19 32 drivers/mtd 20 28 drivers/ide
Re: [Ksummit-discuss] [PATCH] CodingStyle: Inclusive Terminology
On Mon, Jul 6, 2020 at 3:54 AM Geert Uytterhoeven wrote: > On Mon, Jul 6, 2020 at 9:22 AM Greg Kroah-Hartman > wrote: > > On Mon, Jul 06, 2020 at 05:10:37PM +1000, NeilBrown wrote: > > > On Sat, Jul 04 2020, Matthew Wilcox wrote: > > > > Another suggestion for "slave" replacement should be "device". This is > > > > in > > > > the context of the w1 bus which is by far the largest user of the > > > > master/slave terminology in the kernel. > > W1 the largest? Really? I should have said "most obnoxious". They managed to put that terminology in filenames, eg drivers/w1/slaves and Documentation/w1/slaves In terms of number of lines of code using the word, it's only seventh in drivers/: $ for i in drivers/*; do c=$(find $i -type f |xargs grep slave |wc -l); echo "$c $i"; done |sort -rn |head 5218 drivers/net 1341 drivers/dma 988 drivers/i2c 695 drivers/gpu 666 drivers/soundwire 665 drivers/spi 559 drivers/w1 461 drivers/infiniband 389 drivers/media 301 drivers/scsi
Re: [Ksummit-discuss] [PATCH] CodingStyle: Inclusive Terminology
On Mon, Jul 06, 2020 at 09:53:55AM +0200, Geert Uytterhoeven wrote: > On Mon, Jul 6, 2020 at 9:22 AM Greg Kroah-Hartman > wrote: > > look at the USB spec for an example of these terms being used in this > > way for many decades. > > And when does the "gadget" enter the show? ;-) It doesn't, as the USB spec does not describe that in any reasonable way for us to use when dealing with drivers for both "types" of devices. So we came up with the word "gadget" on purpose to be able to talk about those things in a specific manner. thanks, greg k-h
Re: [Ksummit-discuss] [PATCH] CodingStyle: Inclusive Terminology
On Mon, Jul 6, 2020 at 9:22 AM Greg Kroah-Hartman
wrote:
> On Mon, Jul 06, 2020 at 05:10:37PM +1000, NeilBrown wrote:
> > On Sat, Jul 04 2020, Matthew Wilcox wrote:
> > > Another suggestion for "slave" replacement should be "device". This is in
> > > the context of the w1 bus which is by far the largest user of the
> > > master/slave terminology in the kernel.
W1 the largest? Really?
> >
> > Ugh. Please, no. "device" doesn't mean anything, in that you can use
> > it to refer to any thing. (i.e. it is almost semantically equivalent to
> > "thing").
>
> Context is everything, you can have a "controller" and a "device" that
> the controller controls. These are common terms in many specs today,
A "controller" is also any block of electronics that performs a function
involving a state machine.
So for SPI and I2C, we'll have Linux drivers talking to an "SPI controller
controller", an "SPI device controller", an "I2C controller controller",
and an "I2C device controller".
For W1, Linux is still limited to supporting "W1 controller controllers",
but supporting "W1 device controllers" might be just beyond the horizon...
> look at the USB spec for an example of these terms being used in this
> way for many decades.
And when does the "gadget" enter the show? ;-)
P.S. In Dutch, we just assimilate all English technical words, and
they'll only have that specific meaning. E.g. if someone
talks about the "cloud", even lay people know they're not talking
about those things that may ruin your holiday outside.
Gr{oetje,eeting}s,
Geert
--
Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- ge...@linux-m68k.org
In personal conversations with technical people, I call myself a hacker. But
when I'm talking to journalists I just say "programmer" or something like that.
-- Linus Torvalds
Re: [Ksummit-discuss] [PATCH] CodingStyle: Inclusive Terminology
On Mon, Jul 06, 2020 at 05:10:37PM +1000, NeilBrown wrote: > On Sat, Jul 04 2020, Matthew Wilcox wrote: > > > Another suggestion for "slave" replacement should be "device". This is in > > the context of the w1 bus which is by far the largest user of the > > master/slave terminology in the kernel. > > Ugh. Please, no. "device" doesn't mean anything, in that you can use > it to refer to any thing. (i.e. it is almost semantically equivalent to > "thing"). Context is everything, you can have a "controller" and a "device" that the controller controls. These are common terms in many specs today, look at the USB spec for an example of these terms being used in this way for many decades. So while the term might be generic, like the word it is replacing, it makes sense when used in the context it will show up in, so it is a good replacement in many instances. thanks, greg k-h
Re: [Ksummit-discuss] [PATCH] CodingStyle: Inclusive Terminology
On Sat, Jul 04 2020, Matthew Wilcox wrote: > Another suggestion for "slave" replacement should be "device". This is in > the context of the w1 bus which is by far the largest user of the > master/slave terminology in the kernel. Ugh. Please, no. "device" doesn't mean anything, in that you can use it to refer to any thing. (i.e. it is almost semantically equivalent to "thing"). Look in /sys/devices. Everything in there is a device, and (nearly) every thing is in there. NeilBrown > > On Sat., Jul. 4, 2020, 16:19 Dan Williams, wrote: > >> Recent events have prompted a Linux position statement on inclusive >> terminology. Given that Linux maintains a coding-style and its own >> idiomatic set of terminology here is a proposal to answer the call to >> replace non-inclusive terminology. >> >> Cc: Jonathan Corbet >> Cc: Kees Cook >> Signed-off-by: Chris Mason >> Signed-off-by: Greg Kroah-Hartman >> Signed-off-by: Dan Williams >> --- >> Documentation/process/coding-style.rst | 12 >> Documentation/process/inclusive-terminology.rst | 64 >> +++ >> Documentation/process/index.rst |1 >> 3 files changed, 77 insertions(+) >> create mode 100644 Documentation/process/inclusive-terminology.rst >> >> diff --git a/Documentation/process/coding-style.rst >> b/Documentation/process/coding-style.rst >> index 2657a55c6f12..4b15ab671089 100644 >> --- a/Documentation/process/coding-style.rst >> +++ b/Documentation/process/coding-style.rst >> @@ -319,6 +319,18 @@ If you are afraid to mix up your local variable >> names, you have another >> problem, which is called the function-growth-hormone-imbalance syndrome. >> See chapter 6 (Functions). >> >> +For symbol names, avoid introducing new usage of the words 'slave' and >> +'blacklist'. Recommended replacements for 'slave' are: 'secondary', >> +'subordinate', 'replica', 'responder', 'follower', 'proxy', or >> +'performer'. Recommended replacements for blacklist are: 'blocklist' or >> +'denylist'. >> + >> +Exceptions for introducing new usage is to maintain a userspace ABI, or >> +when updating code for an existing (as of 2020) hardware or protocol >> +specification that mandates those terms. For new specifications consider >> +translating specification usage of the terminology to the kernel coding >> +standard where possible. See :ref:`process/inclusive-terminology.rst >> +` for details. >> >> 5) Typedefs >> --- >> diff --git a/Documentation/process/inclusive-terminology.rst >> b/Documentation/process/inclusive-terminology.rst >> new file mode 100644 >> index ..a8eb26690eb4 >> --- /dev/null >> +++ b/Documentation/process/inclusive-terminology.rst >> @@ -0,0 +1,64 @@ >> +.. _inclusiveterminology: >> + >> +Linux kernel inclusive terminology >> +== >> + >> +The Linux kernel is a global software project, and in 2020 there was a >> +global reckoning on race relations that caused many organizations to >> +re-evaluate their policies and practices relative to the inclusion of >> +people of African descent. This document describes why the 'Naming' >> +section in :ref:`process/coding-style.rst ` recommends >> +avoiding usage of 'slave' and 'blacklist' in new additions to the Linux >> +kernel. >> + >> +On the triviality of replacing words >> + >> + >> +The African slave trade was a brutal system of human misery deployed at >> +global scale. Some word choice decisions in a modern software project >> +does next to nothing to compensate for that legacy. So why put any >> +effort into something so trivial in comparison? Because the goal is not >> +to repair, or erase the past. The goal is to maximize availability and >> +efficiency of the global developer community to participate in the Linux >> +kernel development process. >> + >> +Word choice and developer efficiency >> + >> + >> +Why does any software project go through the trouble of developing a >> +document like :ref:`process/coding-style.rst `? It does so >> +because a common coding style maximizes the efficiency of both >> +maintainers and developers. Developers learn common design patterns and >> +idiomatic expressions while maintainers can spot deviations from those >> +norms. Even non-compliant whitespace is considered a leading indicator >> +to deeper problems in a patchset. Coding style violations are known to >> +take a maintainer "out of the zone" of reviewing code. Maintainers are >> +also sensitive to word choice across specifications and often choose to >> +deploy Linux terminology to replace non-idiomatic word-choice in a >> +specification. >> + >> +Non-inclusive terminology has that same distracting effect which is why >> +it is a style issue for Linux, it injures developer efficiency. >> + >> +Of course it is around this point someone jumps in with an etymological >> +argument about why people should not be offended. Etymological
Re: [Ksummit-discuss] [PATCH] CodingStyle: Inclusive Terminology
On Sat, Jul 04 2020, Matthew Wilcox wrote: > Another suggestion for "slave" replacement should be "device". This is in > the context of the w1 bus which is by far the largest user of the > master/slave terminology in the kernel. Ugh. Please, no. "device" doesn't mean anything, in that you can use it to refer to any thing. (i.e. it is almost semantically equivalent to "thing"). Look in /sys/devices. Everything in there is a device, and (nearly) every thing is in there. NeilBrown > > On Sat., Jul. 4, 2020, 16:19 Dan Williams, wrote: > >> Recent events have prompted a Linux position statement on inclusive >> terminology. Given that Linux maintains a coding-style and its own >> idiomatic set of terminology here is a proposal to answer the call to >> replace non-inclusive terminology. >> >> Cc: Jonathan Corbet >> Cc: Kees Cook >> Signed-off-by: Chris Mason >> Signed-off-by: Greg Kroah-Hartman >> Signed-off-by: Dan Williams >> --- >> Documentation/process/coding-style.rst | 12 >> Documentation/process/inclusive-terminology.rst | 64 >> +++ >> Documentation/process/index.rst |1 >> 3 files changed, 77 insertions(+) >> create mode 100644 Documentation/process/inclusive-terminology.rst >> >> diff --git a/Documentation/process/coding-style.rst >> b/Documentation/process/coding-style.rst >> index 2657a55c6f12..4b15ab671089 100644 >> --- a/Documentation/process/coding-style.rst >> +++ b/Documentation/process/coding-style.rst >> @@ -319,6 +319,18 @@ If you are afraid to mix up your local variable >> names, you have another >> problem, which is called the function-growth-hormone-imbalance syndrome. >> See chapter 6 (Functions). >> >> +For symbol names, avoid introducing new usage of the words 'slave' and >> +'blacklist'. Recommended replacements for 'slave' are: 'secondary', >> +'subordinate', 'replica', 'responder', 'follower', 'proxy', or >> +'performer'. Recommended replacements for blacklist are: 'blocklist' or >> +'denylist'. >> + >> +Exceptions for introducing new usage is to maintain a userspace ABI, or >> +when updating code for an existing (as of 2020) hardware or protocol >> +specification that mandates those terms. For new specifications consider >> +translating specification usage of the terminology to the kernel coding >> +standard where possible. See :ref:`process/inclusive-terminology.rst >> +` for details. >> >> 5) Typedefs >> --- >> diff --git a/Documentation/process/inclusive-terminology.rst >> b/Documentation/process/inclusive-terminology.rst >> new file mode 100644 >> index ..a8eb26690eb4 >> --- /dev/null >> +++ b/Documentation/process/inclusive-terminology.rst >> @@ -0,0 +1,64 @@ >> +.. _inclusiveterminology: >> + >> +Linux kernel inclusive terminology >> +== >> + >> +The Linux kernel is a global software project, and in 2020 there was a >> +global reckoning on race relations that caused many organizations to >> +re-evaluate their policies and practices relative to the inclusion of >> +people of African descent. This document describes why the 'Naming' >> +section in :ref:`process/coding-style.rst ` recommends >> +avoiding usage of 'slave' and 'blacklist' in new additions to the Linux >> +kernel. >> + >> +On the triviality of replacing words >> + >> + >> +The African slave trade was a brutal system of human misery deployed at >> +global scale. Some word choice decisions in a modern software project >> +does next to nothing to compensate for that legacy. So why put any >> +effort into something so trivial in comparison? Because the goal is not >> +to repair, or erase the past. The goal is to maximize availability and >> +efficiency of the global developer community to participate in the Linux >> +kernel development process. >> + >> +Word choice and developer efficiency >> + >> + >> +Why does any software project go through the trouble of developing a >> +document like :ref:`process/coding-style.rst `? It does so >> +because a common coding style maximizes the efficiency of both >> +maintainers and developers. Developers learn common design patterns and >> +idiomatic expressions while maintainers can spot deviations from those >> +norms. Even non-compliant whitespace is considered a leading indicator >> +to deeper problems in a patchset. Coding style violations are known to >> +take a maintainer "out of the zone" of reviewing code. Maintainers are >> +also sensitive to word choice across specifications and often choose to >> +deploy Linux terminology to replace non-idiomatic word-choice in a >> +specification. >> + >> +Non-inclusive terminology has that same distracting effect which is why >> +it is a style issue for Linux, it injures developer efficiency. >> + >> +Of course it is around this point someone jumps in with an etymological >> +argument about why people should not be offended. Etymological
Re: [Ksummit-discuss] [PATCH] CodingStyle: Inclusive Terminology
Hi Dave, On Sun, 5 Jul 2020 12:56:23 +1000 Dave Airlie wrote: > > Sorry I misdirected what you said a bit, and I did misinterpret as > Australia also has it's own indigenous slavery issues, (and non-indigenous :-() > I was trying to stop the "white slavery" is a thing crew from turning > up on this. > > Apologies for accidentally implying something what you hadn't said. Sure No worries, mate :-) -- Cheers, Stephen Rothwell pgp9iVXH1cll9.pgp Description: OpenPGP digital signature
Re: [Ksummit-discuss] [PATCH] CodingStyle: Inclusive Terminology
On Sun, 2020-07-05 at 12:56 +1000, Dave Airlie wrote: > On Sun, 5 Jul 2020 at 12:12, Stephen Rothwell > wrote: [...] > > > As for the non-black slavery, others have never pointed this out > > > > (I did not say "non-black") > > > > Sorry I misdirected what you said a bit, and I did misinterpret as > Australia also has it's own indigenous slavery issues, > > I was trying to stop the "white slavery" is a thing crew from turning > up on this. > > Apologies for accidentally implying something what you hadn't said. Not at all, thank you; you just gave a precise illustration of my point: putting statements like this in the kernel acts as a magnet for this type of disagreement ... and not just from honourable people. Developers can honestly disagree about this sort of thing, while supporting the aim of using inclusive language. That's why this file shouldn't be in the kernel tree. James
Re: [Ksummit-discuss] [PATCH] CodingStyle: Inclusive Terminology
On Sun, 5 Jul 2020 at 12:12, Stephen Rothwell wrote: > > Hi Dave, > > On Sun, 5 Jul 2020 09:34:57 +1000 Dave Airlie wrote: > > > > On Sun, 5 Jul 2020 at 06:45, Stephen Rothwell wrote: > > > > > > On Sat, 04 Jul 2020 13:02:51 -0700 Dan Williams > > > wrote: > > > > > > > > +The Linux kernel is a global software project, and in 2020 there was a > > > > +global reckoning on race relations that caused many organizations to > > > > +re-evaluate their policies and practices relative to the inclusion of > > > > +people of African descent. This document describes why the 'Naming' > > > > > > I feel a need to point out that racial issues are wider than just > > > people of African descent ... Also, others have pointed out that > > > slavery is not just restricted to those of African descent. > > > > The racial issues are wider than that, and even wider again I'm sure, > > but in 2020 this is as good a place to start as any, and the trigger > > as that sentence says was in 2020, there was a reckoning about it > > mainly due to people of African descent. That trigger has had flow on > > effects in other countries, but I'm not sure that sentence in any way > > diminishes that, it's merely an introduction to why this change is > > happening now. > > And reading it again in the (actual) light of day, I see you are right > and I misinterpreted this. > > > As for the non-black slavery, others have never pointed this out > > (I did not say "non-black") > Sorry I misdirected what you said a bit, and I did misinterpret as Australia also has it's own indigenous slavery issues, I was trying to stop the "white slavery" is a thing crew from turning up on this. Apologies for accidentally implying something what you hadn't said. Dave.
Re: [Ksummit-discuss] [PATCH] CodingStyle: Inclusive Terminology
On Sun, 5 Jul 2020 at 10:10, Matthew Wilcox wrote: > > Erm, red-black trees don't have a derivation from gambling terminology > either. The wikipedia article says: > > In a 1978 paper, "A Dichromatic Framework for Balanced Trees",[6] Leonidas J. > Guibas and Robert Sedgewick derived the red-black tree from the symmetric > binary B-tree.[7] The color "red" was chosen because it was the best-looking > color produced by the color laser printer available to the authors while > working at Xerox PARC.[8] Another response from Guibas states that it was > because of the red and black pens available to them to draw the trees.[9] > > Left-right tree makes no sense. It doesn't distinguish the rbtree from its > predecessor the avl tree. I don't think it's helpful to rename a standard > piece of computing terminology unless it's actually hurting us to have it. > Obviously if it were called a "master-slave" tree, I would be in favour of > renaming it. As I said "it means nothing if you've never interacted with gambling culture," red black in the context of the trees as zero meaning other than as a name to find it on the internet, Search for that name enough and you will undoubtedly be getting ads for online roulette sites within hours, if you have a problem gambling past, this might not be the desired effect you'd want. The reasons something was named a particular thing can and will be different from what a societal context for them means now, and I believe it's more important to worry about current societal contexts than legacy historical namings. I'm not seriously suggesting we rename red-black trees, but if someone who had a problematic gambling background had issues with them I'd definitely be open for considering it. Dave.
Re: [Tech-board-discuss] [Ksummit-discuss] [PATCH] CodingStyle: Inclusive Terminology
On 7/4/20 6:10 PM, Kees Cook wrote: > On Sat, Jul 04, 2020 at 08:10:33PM -0400, Matthew Wilcox wrote: >> Left-right tree makes no sense. It doesn't distinguish the rbtree from its >> predecessor the avl tree. I don't think it's helpful to rename a standard >> piece of computing terminology unless it's actually hurting us to have it. >> Obviously if it were called a "master-slave" tree, I would be in favour of >> renaming it. > > (No one has suggested renaming red/black trees, so I think the > slippery-slope argument can be set aside here.) Did you read this message? https://lore.kernel.org/ksummit-discuss/CAPM=9ty0til_qm_ufv0s0vtarkz_f-anngc+amdm5ljgaha...@mail.gmail.com/ > As for the actual proposal on white/black-list, I've always been annoyed > by the poor description it provides (and I get to see it A LOT being > the seccomp maintainer). I welcome allow/deny-list (though the change is > not new for seccomp -- the man pages were updated last year (thanks > mkerrisk). :) > -- ~Randy
Re: [Ksummit-discuss] [PATCH] CodingStyle: Inclusive Terminology
Hi Dave, On Sun, 5 Jul 2020 09:34:57 +1000 Dave Airlie wrote: > > On Sun, 5 Jul 2020 at 06:45, Stephen Rothwell wrote: > > > > On Sat, 04 Jul 2020 13:02:51 -0700 Dan Williams > > wrote: > > > > > > +The Linux kernel is a global software project, and in 2020 there was a > > > +global reckoning on race relations that caused many organizations to > > > +re-evaluate their policies and practices relative to the inclusion of > > > +people of African descent. This document describes why the 'Naming' > > > > I feel a need to point out that racial issues are wider than just > > people of African descent ... Also, others have pointed out that > > slavery is not just restricted to those of African descent. > > The racial issues are wider than that, and even wider again I'm sure, > but in 2020 this is as good a place to start as any, and the trigger > as that sentence says was in 2020, there was a reckoning about it > mainly due to people of African descent. That trigger has had flow on > effects in other countries, but I'm not sure that sentence in any way > diminishes that, it's merely an introduction to why this change is > happening now. And reading it again in the (actual) light of day, I see you are right and I misinterpreted this. > As for the non-black slavery, others have never pointed this out (I did not say "non-black") > before in 30 years of master/slave terminology? surely if white > slavery was as big a problem, they be as supportive of this, even more (nor did I say "white slavery") > so. It speaks volumes that I've never heard white slavery as a problem > once in 30 years, but now I'm hearing about it a few times, and > somehow as an excuse not to support this. I was merely referring to some of the posts in the us...@linux.kernel.org mailing list. Also, I made no statement about my support (or otherwise) for any of this. -- Cheers, Stephen Rothwell pgpq0Xsz_EX5d.pgp Description: OpenPGP digital signature
Re: [Tech-board-discuss] [Ksummit-discuss] [PATCH] CodingStyle: Inclusive Terminology
On Sat, Jul 04, 2020 at 08:10:33PM -0400, Matthew Wilcox wrote: > Left-right tree makes no sense. It doesn't distinguish the rbtree from its > predecessor the avl tree. I don't think it's helpful to rename a standard > piece of computing terminology unless it's actually hurting us to have it. > Obviously if it were called a "master-slave" tree, I would be in favour of > renaming it. (No one has suggested renaming red/black trees, so I think the slippery-slope argument can be set aside here.) As for the actual proposal on white/black-list, I've always been annoyed by the poor description it provides (and I get to see it A LOT being the seccomp maintainer). I welcome allow/deny-list (though the change is not new for seccomp -- the man pages were updated last year (thanks mkerrisk). :) -- Kees Cook
Re: [Ksummit-discuss] [PATCH] CodingStyle: Inclusive Terminology
On Sun, 5 Jul 2020 at 06:19, Dan Williams wrote: > > Recent events have prompted a Linux position statement on inclusive > terminology. Given that Linux maintains a coding-style and its own > idiomatic set of terminology here is a proposal to answer the call to > replace non-inclusive terminology. > > Cc: Jonathan Corbet > Cc: Kees Cook > Signed-off-by: Chris Mason > Signed-off-by: Greg Kroah-Hartman > Signed-off-by: Dan Williams I'm sure the language could be fine tuned, but the intent is something I support. Acked-by: Dave Airlie > --- > Documentation/process/coding-style.rst | 12 > Documentation/process/inclusive-terminology.rst | 64 > +++ > Documentation/process/index.rst |1 > 3 files changed, 77 insertions(+) > create mode 100644 Documentation/process/inclusive-terminology.rst > > diff --git a/Documentation/process/coding-style.rst > b/Documentation/process/coding-style.rst > index 2657a55c6f12..4b15ab671089 100644 > --- a/Documentation/process/coding-style.rst > +++ b/Documentation/process/coding-style.rst > @@ -319,6 +319,18 @@ If you are afraid to mix up your local variable names, > you have another > problem, which is called the function-growth-hormone-imbalance syndrome. > See chapter 6 (Functions). > > +For symbol names, avoid introducing new usage of the words 'slave' and > +'blacklist'. Recommended replacements for 'slave' are: 'secondary', > +'subordinate', 'replica', 'responder', 'follower', 'proxy', or > +'performer'. Recommended replacements for blacklist are: 'blocklist' or > +'denylist'. > + > +Exceptions for introducing new usage is to maintain a userspace ABI, or > +when updating code for an existing (as of 2020) hardware or protocol > +specification that mandates those terms. For new specifications consider > +translating specification usage of the terminology to the kernel coding > +standard where possible. See :ref:`process/inclusive-terminology.rst > +` for details. > > 5) Typedefs > --- > diff --git a/Documentation/process/inclusive-terminology.rst > b/Documentation/process/inclusive-terminology.rst > new file mode 100644 > index ..a8eb26690eb4 > --- /dev/null > +++ b/Documentation/process/inclusive-terminology.rst > @@ -0,0 +1,64 @@ > +.. _inclusiveterminology: > + > +Linux kernel inclusive terminology > +== > + > +The Linux kernel is a global software project, and in 2020 there was a > +global reckoning on race relations that caused many organizations to > +re-evaluate their policies and practices relative to the inclusion of > +people of African descent. This document describes why the 'Naming' > +section in :ref:`process/coding-style.rst ` recommends > +avoiding usage of 'slave' and 'blacklist' in new additions to the Linux > +kernel. > + > +On the triviality of replacing words > + > + > +The African slave trade was a brutal system of human misery deployed at > +global scale. Some word choice decisions in a modern software project > +does next to nothing to compensate for that legacy. So why put any > +effort into something so trivial in comparison? Because the goal is not > +to repair, or erase the past. The goal is to maximize availability and > +efficiency of the global developer community to participate in the Linux > +kernel development process. > + > +Word choice and developer efficiency > + > + > +Why does any software project go through the trouble of developing a > +document like :ref:`process/coding-style.rst `? It does so > +because a common coding style maximizes the efficiency of both > +maintainers and developers. Developers learn common design patterns and > +idiomatic expressions while maintainers can spot deviations from those > +norms. Even non-compliant whitespace is considered a leading indicator > +to deeper problems in a patchset. Coding style violations are known to > +take a maintainer "out of the zone" of reviewing code. Maintainers are > +also sensitive to word choice across specifications and often choose to > +deploy Linux terminology to replace non-idiomatic word-choice in a > +specification. > + > +Non-inclusive terminology has that same distracting effect which is why > +it is a style issue for Linux, it injures developer efficiency. > + > +Of course it is around this point someone jumps in with an etymological > +argument about why people should not be offended. Etymological arguments > +do not scale. The scope and pace of Linux to reach new developers > +exceeds the ability of historical terminology defenders to describe "no, > +not that connotation". The revelation of 2020 was that black voices were > +heard on a global scale and the Linux kernel project has done its small > +part to answer that call as it wants black voices, among all voices, in > +its developer community. > + > +Really, 'blacklist' too? > + > + > +W
Re: [Ksummit-discuss] [PATCH] CodingStyle: Inclusive Terminology
'. Colors to represent a policy requires an indirection. The > > how about: > Using colors to represent a policy requires an indirection. I'd totally submit that red/black trees while in no way racist, are a horrible indirection, as it means nothing if you've never interacted with gambling culture, (and maybe James Bond movies). left/right trees make naturally more sense and translate into more languages, so yes I think removal of color naming is a good thing even for non-racist reasonings. Dave.
Re: [Ksummit-discuss] [PATCH] CodingStyle: Inclusive Terminology
On Sun, 5 Jul 2020 at 06:45, Stephen Rothwell wrote: > > Hi Dan, > > On Sat, 04 Jul 2020 13:02:51 -0700 Dan Williams > wrote: > > > > +Linux kernel inclusive terminology > > +== > > + > > +The Linux kernel is a global software project, and in 2020 there was a > > +global reckoning on race relations that caused many organizations to > > +re-evaluate their policies and practices relative to the inclusion of > > +people of African descent. This document describes why the 'Naming' > > I feel a need to point out that racial issues are wider than just > people of African descent ... Also, others have pointed out that > slavery is not just restricted to those of African descent. The racial issues are wider than that, and even wider again I'm sure, but in 2020 this is as good a place to start as any, and the trigger as that sentence says was in 2020, there was a reckoning about it mainly due to people of African descent. That trigger has had flow on effects in other countries, but I'm not sure that sentence in any way diminishes that, it's merely an introduction to why this change is happening now. As for the non-black slavery, others have never pointed this out before in 30 years of master/slave terminology? surely if white slavery was as big a problem, they be as supportive of this, even more so. It speaks volumes that I've never heard white slavery as a problem once in 30 years, but now I'm hearing about it a few times, and somehow as an excuse not to support this. Dave.
Re: [Ksummit-discuss] [PATCH] CodingStyle: Inclusive Terminology
On Sat, Jul 4, 2020 at 1:19 PM Dan Williams wrote: > > Recent events have prompted a Linux position statement on inclusive > terminology. Given that Linux maintains a coding-style and its own > idiomatic set of terminology here is a proposal to answer the call to > replace non-inclusive terminology. > > Cc: Jonathan Corbet > Cc: Kees Cook > Signed-off-by: Chris Mason > Signed-off-by: Greg Kroah-Hartman > Signed-off-by: Dan Williams I'm happy to support this, I agree with the general approach as well as the motivations thereof. At your discretion, feel free to add: Signed-off-by: Olof Johansson Or Acked-by, or whatever other label you prefer to use to show agreement and support. -Olof
Re: [Ksummit-discuss] [PATCH] CodingStyle: Inclusive Terminology
Hi Dan, On Sat, 04 Jul 2020 13:02:51 -0700 Dan Williams wrote: > > +Linux kernel inclusive terminology > +== > + > +The Linux kernel is a global software project, and in 2020 there was a > +global reckoning on race relations that caused many organizations to > +re-evaluate their policies and practices relative to the inclusion of > +people of African descent. This document describes why the 'Naming' I feel a need to point out that racial issues are wider than just people of African descent ... Also, others have pointed out that slavery is not just restricted to those of African descent. -- Cheers, Stephen Rothwell pgpPSyeehNUWj.pgp Description: OpenPGP digital signature
