CodingStyle: Inclusive Terminology
PATCH v3 1/1 CodingStyle: Inclusive Terminology
Linux maintains a coding-style and its own idiomatic set of terminology. Update the style guidelines to recommend replacements for the terms master/slave and blacklist/whitelist.
---
Changes since v2 [1]:
- Pick up missed sign-offs and acks from Jon, Shuah, and Christian (sorry about missing those earlier).
- Reformat the replacement list to make it easier to read.
- Add 'controller' as a suggested replacement (Kees and Mark)
- Fix up the paired term for 'performer' to be 'director' (Kees)
- Collect some new acks, reviewed-by's, and sign-offs for v2.
- Fix up Chris's email
Documentation/process/coding-style.rst | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+)
Documentation/process/coding-style.rst +20 -0
@@ -319,6 +319,26 @@ 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 and documentation, avoid introducing new usage of +'master / slave' (or 'slave' independent of 'master') and 'blacklist / +whitelist'. + +Recommended replacements for 'master / slave' are: + '{primary,main} / {secondary,replica,subordinate}' + '{initiator,requester} / {target,responder}' + '{controller,host} / {device,worker,proxy}' + 'leader / follower' + 'director / performer' + +Recommended replacements for 'blacklist/whitelist' are: + 'denylist / allowlist' + 'blocklist / passlist' + +Exceptions for introducing new usage is to maintain a userspace ABI/API, +or when updating code for an existing (as of 2020) hardware or protocol +specification that mandates those terms. For new specifications +translate specification usage of the terminology to the kernel coding +standard where possible. 5) Typedefs -----------
Quoted 5 lines · Dan Williams
Linux maintains a coding-style and its own idiomatic set of terminology. Update the style guidelines to recommend replacements for the terms master/slave and blacklist/whitelist.
Quoted 16 lines
Link http://lore.kernel.org/r/159389297140.2210796.13590142254668787525.stgit@dwillia2-desk3.amr.corp.intel.com open hereAcked-by Randy Dunlap <[email protected]>Acked-by Dave Airlie <[email protected]>Acked-by SeongJae Park <[email protected]>Acked-by James Bottomley <[email protected]>Reviewed-by Mark Brown <[email protected]>Signed-off-by Theodore Ts'o <[email protected]>Signed-off-by Shuah Khan <[email protected]>Signed-off-by Dan Carpenter <[email protected]>Signed-off-by Kees Cook <[email protected]>Signed-off-by Olof Johansson <[email protected]>Signed-off-by Jonathan Corbet <[email protected]>Signed-off-by Chris Mason <[email protected]>Signed-off-by Greg Kroah-Hartman <[email protected]>Signed-off-by Dan Williams <[email protected]>
Replied to the old version, once more here so it's not lost.
Quoted 57 lines
---
Changes since v2 [1]:
- Pick up missed sign-offs and acks from Jon, Shuah, and Christian (sorry about missing those earlier).- Reformat the replacement list to make it easier to read.
- Add 'controller' as a suggested replacement (Kees and Mark)
- Fix up the paired term for 'performer' to be 'director' (Kees)
- Collect some new acks, reviewed-by's, and sign-offs for v2.
- Fix up Chris's email
Documentation/process/coding-style.rst | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+)Documentation/process/coding-style.rst +20
-0@@ -319,6 +319,26 @@ 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 and documentation, avoid introducing new usage of +'master / slave' (or 'slave' independent of 'master') and 'blacklist / +whitelist'. + +Recommended replacements for 'master / slave' are: + '{primary,main} / {secondary,replica,subordinate}' + '{initiator,requester} / {target,responder}' + '{controller,host} / {device,worker,proxy}' + 'leader / follower' + 'director / performer' + +Recommended replacements for 'blacklist/whitelist' are: + 'denylist / allowlist' + 'blocklist / passlist' + +Exceptions for introducing new usage is to maintain a userspace ABI/API, +or when updating code for an existing (as of 2020) hardware or protocol +specification that mandates those terms. For new specifications +translate specification usage of the terminology to the kernel coding +standard where possible. 5) Typedefs -----------_______________________________________________
Ksummit-discuss mailing list
[email protected]
https://lists.linuxfoundation.org/mailman/listinfo/ksummit-discuss
Signature · 3 lines
Daniel Vetter Software Engineer, Intel Corporation http://blog.ffwll.ch
Quoted 24 lines · Daniel Vetter
Quoted 5 lines · Dan Williams
Linux maintains a coding-style and its own idiomatic set of terminology. Update the style guidelines to recommend replacements for the terms master/slave and blacklist/whitelist.
Quoted 16 lines
Link http://lore.kernel.org/r/159389297140.2210796.13590142254668787525.stgit@dwillia2-desk3.amr.corp.intel.com open hereAcked-by Randy Dunlap <[email protected]>Acked-by Dave Airlie <[email protected]>Acked-by SeongJae Park <[email protected]>Acked-by James Bottomley <[email protected]>Reviewed-by Mark Brown <[email protected]>Signed-off-by Theodore Ts'o <[email protected]>Signed-off-by Shuah Khan <[email protected]>Signed-off-by Dan Carpenter <[email protected]>Signed-off-by Kees Cook <[email protected]>Signed-off-by Olof Johansson <[email protected]>Signed-off-by Jonathan Corbet <[email protected]>Signed-off-by Chris Mason <[email protected]>Signed-off-by Greg Kroah-Hartman <[email protected]>Signed-off-by Dan Williams <[email protected]>
Quoted 3 lines
Replied to the old version, once more here so it's not lost.
Acked-by Daniel Vetter <[email protected]>
Got it, thanks Daniel.
Quoted 4 lines · Dan Williams
Linux maintains a coding-style and its own idiomatic set of terminology. Update the style guidelines to recommend replacements for the terms master/slave and blacklist/whitelist.
Quoted 16 lines
Link http://lore.kernel.org/r/159389297140.2210796.13590142254668787525.stgit@dwillia2-desk3.amr.corp.intel.com open hereAcked-by Randy Dunlap <[email protected]>Acked-by Dave Airlie <[email protected]>Acked-by SeongJae Park <[email protected]>Acked-by James Bottomley <[email protected]>Reviewed-by Mark Brown <[email protected]>Signed-off-by Theodore Ts'o <[email protected]>Signed-off-by Shuah Khan <[email protected]>Signed-off-by Dan Carpenter <[email protected]>Signed-off-by Kees Cook <[email protected]>Signed-off-by Olof Johansson <[email protected]>Signed-off-by Jonathan Corbet <[email protected]>Signed-off-by Chris Mason <[email protected]>Signed-off-by Greg Kroah-Hartman <[email protected]>Signed-off-by Dan Williams <[email protected]>
Quoted 58 lines
---
Changes since v2 [1]:
- Pick up missed sign-offs and acks from Jon, Shuah, and Christian (sorry about missing those earlier).- Reformat the replacement list to make it easier to read.
- Add 'controller' as a suggested replacement (Kees and Mark)
- Fix up the paired term for 'performer' to be 'director' (Kees)
- Collect some new acks, reviewed-by's, and sign-offs for v2.
- Fix up Chris's email
Documentation/process/coding-style.rst | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+)Documentation/process/coding-style.rst +20
-0@@ -319,6 +319,26 @@ 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 and documentation, avoid introducing new usage of +'master / slave' (or 'slave' independent of 'master') and 'blacklist / +whitelist'. + +Recommended replacements for 'master / slave' are: + '{primary,main} / {secondary,replica,subordinate}' + '{initiator,requester} / {target,responder}' + '{controller,host} / {device,worker,proxy}' + 'leader / follower' + 'director / performer' + +Recommended replacements for 'blacklist/whitelist' are: + 'denylist / allowlist' + 'blocklist / passlist' + +Exceptions for introducing new usage is to maintain a userspace ABI/API, +or when updating code for an existing (as of 2020) hardware or protocol +specification that mandates those terms. For new specifications +translate specification usage of the terminology to the kernel coding +standard where possible. 5) Typedefs -----------_______________________________________________
Ksummit-discuss mailing list
[email protected]
https://lists.linuxfoundation.org/mailman/listinfo/ksummit-discuss
Quoted 25 lines · Matthias Brugger
Quoted 4 lines · Dan Williams
Linux maintains a coding-style and its own idiomatic set of terminology. Update the style guidelines to recommend replacements for the terms master/slave and blacklist/whitelist.
Quoted 16 lines
Link http://lore.kernel.org/r/159389297140.2210796.13590142254668787525.stgit@dwillia2-desk3.amr.corp.intel.com open hereAcked-by Randy Dunlap <[email protected]>Acked-by Dave Airlie <[email protected]>Acked-by SeongJae Park <[email protected]>Acked-by James Bottomley <[email protected]>Reviewed-by Mark Brown <[email protected]>Signed-off-by Theodore Ts'o <[email protected]>Signed-off-by Shuah Khan <[email protected]>Signed-off-by Dan Carpenter <[email protected]>Signed-off-by Kees Cook <[email protected]>Signed-off-by Olof Johansson <[email protected]>Signed-off-by Jonathan Corbet <[email protected]>Signed-off-by Chris Mason <[email protected]>Signed-off-by Greg Kroah-Hartman <[email protected]>Signed-off-by Dan Williams <[email protected]>
Quoted 1 line
Reviewed-by Matthias Brugger <[email protected]>
Got it, thanks Matthias.
Quoted 4 lines · Dan Williams
Linux maintains a coding-style and its own idiomatic set of terminology. Update the style guidelines to recommend replacements for the terms master/slave and blacklist/whitelist.
Quoted 8 lines · Andy Lutomirski
Quoted 4 lines · Dan Williams
Linux maintains a coding-style and its own idiomatic set of terminology. Update the style guidelines to recommend replacements for the terms master/slave and blacklist/whitelist.
Acked-by Andy Lutomirski <[email protected]>
Thanks, Andy.
Quoted 63 lines · Dan Williams
Linux maintains a coding-style and its own idiomatic set of terminology. Update the style guidelines to recommend replacements for the terms master/slave and blacklist/whitelist.
Link http://lore.kernel.org/r/159389297140.2210796.13590142254668787525.stgit@dwillia2-desk3.amr.corp.intel.com open hereAcked-by Randy Dunlap <[email protected]>Acked-by Dave Airlie <[email protected]>Acked-by SeongJae Park <[email protected]>Acked-by James Bottomley <[email protected]>Reviewed-by Mark Brown <[email protected]>Signed-off-by Theodore Ts'o <[email protected]>Signed-off-by Shuah Khan <[email protected]>Signed-off-by Dan Carpenter <[email protected]>Signed-off-by Kees Cook <[email protected]>Signed-off-by Olof Johansson <[email protected]>Signed-off-by Jonathan Corbet <[email protected]>Signed-off-by Chris Mason <[email protected]>Signed-off-by Greg Kroah-Hartman <[email protected]>Signed-off-by Dan Williams <[email protected]>---
Changes since v2 [1]:
- Pick up missed sign-offs and acks from Jon, Shuah, and Christian (sorry about missing those earlier).- Reformat the replacement list to make it easier to read.
- Add 'controller' as a suggested replacement (Kees and Mark)
- Fix up the paired term for 'performer' to be 'director' (Kees)
- Collect some new acks, reviewed-by's, and sign-offs for v2.
- Fix up Chris's email
Documentation/process/coding-style.rst | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+)Documentation/process/coding-style.rst +13
-0@@ -319,6 +319,26 @@ 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 and documentation, avoid introducing new usage of +'master / slave' (or 'slave' independent of 'master') and 'blacklist / +whitelist'. + +Recommended replacements for 'master / slave' are: + '{primary,main} / {secondary,replica,subordinate}' + '{initiator,requester} / {target,responder}' + '{controller,host} / {device,worker,proxy}' + 'leader / follower' + 'director / performer' + +Recommended replacements for 'blacklist/whitelist' are: + 'denylist / allowlist'
Documentation/process/coding-style.rst If you are afraid to mix up your local variable names, you have another · line 344
Quoted 10 lines
Documentation/process/coding-style.rst +7
-0+ 'blocklist / passlist' + +Exceptions for introducing new usage is to maintain a userspace ABI/API, +or when updating code for an existing (as of 2020) hardware or protocol +specification that mandates those terms. For new specifications +translate specification usage of the terminology to the kernel coding +standard where possible. 5) Typedefs -----------
Quoted 6 lines · Laura Abbott
Quoted 4 lines · Dan Williams
Linux maintains a coding-style and its own idiomatic set of terminology. Update the style guidelines to recommend replacements for the terms master/slave and blacklist/whitelist.
[..]
Quoted 1 line
Acked-by Laura Abbott <[email protected]>
Thanks, Laura.
Quoted 4 lines · Dan Williams
Linux maintains a coding-style and its own idiomatic set of terminology. Update the style guidelines to recommend replacements for the terms master/slave and blacklist/whitelist.
Quoted 16 lines
Link http://lore.kernel.org/r/159389297140.2210796.13590142254668787525.stgit@dwillia2-desk3.amr.corp.intel.com open hereAcked-by Randy Dunlap <[email protected]>Acked-by Dave Airlie <[email protected]>Acked-by SeongJae Park <[email protected]>Acked-by James Bottomley <[email protected]>Reviewed-by Mark Brown <[email protected]>Signed-off-by Theodore Ts'o <[email protected]>Signed-off-by Shuah Khan <[email protected]>Signed-off-by Dan Carpenter <[email protected]>Signed-off-by Kees Cook <[email protected]>Signed-off-by Olof Johansson <[email protected]>Signed-off-by Jonathan Corbet <[email protected]>Signed-off-by Chris Mason <[email protected]>Signed-off-by Greg Kroah-Hartman <[email protected]>Signed-off-by Dan Williams <[email protected]>
Thanks
--
Gustavo
Quoted 4 lines · Dan Williams
Linux maintains a coding-style and its own idiomatic set of terminology. Update the style guidelines to recommend replacements for the terms master/slave and blacklist/whitelist.
Quoted 16 lines
Link http://lore.kernel.org/r/159389297140.2210796.13590142254668787525.stgit@dwillia2-desk3.amr.corp.intel.com open hereAcked-by Randy Dunlap <[email protected]>Acked-by Dave Airlie <[email protected]>Acked-by SeongJae Park <[email protected]>Acked-by James Bottomley <[email protected]>Reviewed-by Mark Brown <[email protected]>Signed-off-by Theodore Ts'o <[email protected]>Signed-off-by Shuah Khan <[email protected]>Signed-off-by Dan Carpenter <[email protected]>Signed-off-by Kees Cook <[email protected]>Signed-off-by Olof Johansson <[email protected]>Signed-off-by Jonathan Corbet <[email protected]>Signed-off-by Chris Mason <[email protected]>Signed-off-by Greg Kroah-Hartman <[email protected]>Signed-off-by Dan Williams <[email protected]>
Thank you for working on this, Dan!
Hi Dan,
Quoted 4 lines · Dan Williams
Linux maintains a coding-style and its own idiomatic set of terminology. Update the style guidelines to recommend replacements for the terms master/slave and blacklist/whitelist.
Quoted 16 lines
Link http://lore.kernel.org/r/159389297140.2210796.13590142254668787525.stgit@dwillia2-desk3.amr.corp.intel.com open hereAcked-by Randy Dunlap <[email protected]>Acked-by Dave Airlie <[email protected]>Acked-by SeongJae Park <[email protected]>Acked-by James Bottomley <[email protected]>Reviewed-by Mark Brown <[email protected]>Signed-off-by Theodore Ts'o <[email protected]>Signed-off-by Shuah Khan <[email protected]>Signed-off-by Dan Carpenter <[email protected]>Signed-off-by Kees Cook <[email protected]>Signed-off-by Olof Johansson <[email protected]>Signed-off-by Jonathan Corbet <[email protected]>Signed-off-by Chris Mason <[email protected]>Signed-off-by Greg Kroah-Hartman <[email protected]>Signed-off-by Dan Williams <[email protected]>
Thanks for working on this
Quoted 57 lines
---
Changes since v2 [1]:
- Pick up missed sign-offs and acks from Jon, Shuah, and Christian (sorry about missing those earlier).- Reformat the replacement list to make it easier to read.
- Add 'controller' as a suggested replacement (Kees and Mark)
- Fix up the paired term for 'performer' to be 'director' (Kees)
- Collect some new acks, reviewed-by's, and sign-offs for v2.
- Fix up Chris's email
Documentation/process/coding-style.rst | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+)Documentation/process/coding-style.rst +20
-0@@ -319,6 +319,26 @@ 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 and documentation, avoid introducing new usage of +'master / slave' (or 'slave' independent of 'master') and 'blacklist / +whitelist'. + +Recommended replacements for 'master / slave' are: + '{primary,main} / {secondary,replica,subordinate}' + '{initiator,requester} / {target,responder}' + '{controller,host} / {device,worker,proxy}' + 'leader / follower' + 'director / performer' + +Recommended replacements for 'blacklist/whitelist' are: + 'denylist / allowlist' + 'blocklist / passlist' + +Exceptions for introducing new usage is to maintain a userspace ABI/API, +or when updating code for an existing (as of 2020) hardware or protocol +specification that mandates those terms. For new specifications +translate specification usage of the terminology to the kernel coding +standard where possible. 5) Typedefs -----------_______________________________________________
Ksummit-discuss mailing list
[email protected]
https://lists.linuxfoundation.org/mailman/listinfo/ksummit-discuss
Signature · 1 line
~Vinod
Quoted 3 lines · Dan Williams
Linux maintains a coding-style and its own idiomatic set of terminology. Update the style guidelines to recommend replacements for the terms master/slave and blacklist/whitelist.
Documentation/process/coding-style.rst If you are afraid to mix up your local variable names, you have another · line 335
Quoted 4 lines · Dan Williams
Documentation/process/coding-style.rst +3
-0+Recommended replacements for 'blacklist/whitelist' are: + 'denylist / allowlist' + 'blocklist / passlist'
I started looking through the tree now and noticed there are lots of patterns like "whitelisted" or "blacklisted". How can the words fit for those? Actually, there are two cases like:
- Foo is blacklisted
- Allow to load the non-whitelisted cards
Currently I'm replacing the former with "Foo is in denylist", but not sure about the latter case. I thought Kees mentioned about this, but don't remember the proposal...
In anyway, I'm for the action:
thanks,
Takashi
Quoted 7 lines · Takashi Iwai
Documentation/process/coding-style.rst If you are afraid to mix up your local variable names, you have another · line 335
Quoted 4 lines · Dan Williams
Documentation/process/coding-style.rst +3
-0+Recommended replacements for 'blacklist/whitelist' are: + 'denylist / allowlist' + 'blocklist / passlist'
Quoted 8 lines
I started looking through the tree now and noticed there are lots of patterns like "whitelisted" or "blacklisted". How can the words fit for those? Actually, there are two cases like:
- Foo is blacklisted
- Allow to load the non-whitelisted cardsCurrently I'm replacing the former with "Foo is in denylist", but not
In the denylist?
julia
Quoted 15 lines
sure about the latter case. I thought Kees mentioned about this, but don't remember the proposal...
In anyway, I'm for the action:
Acked-by Takashi Iwai <[email protected]>thanks,
Takashi
_______________________________________________
Ksummit-discuss mailing list
[email protected]
https://lists.linuxfoundation.org/mailman/listinfo/ksummit-discuss
Quoted 16 lines · Julia Lawall
Quoted 11 lines · Takashi Iwai
Documentation/process/coding-style.rst If you are afraid to mix up your local variable names, you have another · line 335
Quoted 4 lines · Dan Williams
Documentation/process/coding-style.rst +3
-0+Recommended replacements for 'blacklist/whitelist' are: + 'denylist / allowlist' + 'blocklist / passlist'I started looking through the tree now and noticed there are lots of patterns like "whitelisted" or "blacklisted". How can the words fit for those? Actually, there are two cases like:
Quoted 6 lines
Quoted 4 lines
- Foo is blacklisted
- Allow to load the non-whitelisted cardsCurrently I'm replacing the former with "Foo is in denylist", but not
In the denylist?
Not really, only the allowlist exists in this case.
thanks,
Takashi
Quoted 18 lines · Takashi Iwai
Quoted 16 lines · Julia Lawall
Quoted 11 lines · Takashi Iwai
Documentation/process/coding-style.rst If you are afraid to mix up your local variable names, you have another · line 335
Quoted 4 lines · Dan Williams
Documentation/process/coding-style.rst +3
-0+Recommended replacements for 'blacklist/whitelist' are: + 'denylist / allowlist' + 'blocklist / passlist'I started looking through the tree now and noticed there are lots of patterns like "whitelisted" or "blacklisted". How can the words fit for those? Actually, there are two cases like:
Quoted 8 lines
Quoted 6 lines
Quoted 4 lines
- Foo is blacklisted
- Allow to load the non-whitelisted cardsCurrently I'm replacing the former with "Foo is in denylist", but not
In the denylist?
Not really, only the allowlist exists in this case.
I'm not sure to understand. in denylist is not grammatical. It needs "a" or "the".
Maybe it has to be foo is denylisted? foo is in the implicit denyList? foo is not in the allowList?
julia
Quoted 26 lines · Julia Lawall
Quoted 21 lines · Takashi Iwai
Quoted 19 lines · Julia Lawall
Quoted 14 lines · Takashi Iwai
Documentation/process/coding-style.rst If you are afraid to mix up your local variable names, you have another · line 335
Quoted 4 lines · Dan Williams
Documentation/process/coding-style.rst +3
-0+Recommended replacements for 'blacklist/whitelist' are: + 'denylist / allowlist' + 'blocklist / passlist'I started looking through the tree now and noticed there are lots of patterns like "whitelisted" or "blacklisted". How can the words fit for those? Actually, there are two cases like:
- Foo is blacklisted
- Allow to load the non-whitelisted cards
Quoted 8 lines
Quoted 5 lines
Quoted 3 lines
Quoted 1 line
Currently I'm replacing the former with "Foo is in denylist", but not
In the denylist?
Not really, only the allowlist exists in this case.
I'm not sure to understand. in denylist is not grammatical. It needs "a" or "the".
Ah, now I see how I confused you. The two cases I mentioned in the above are completely individual. They were found in two different drivers. I put those just as two distinct examples for the passive form usages. Sorry for unclearness.
What I meant about the latter was that "not in allowlist" doesn't mean it being "in denylist". It's simply unknown.
Takashi
Quoted 9 lines · Mon, 13 Jul 2020 10:43:28 +0200 (CEST) Julia Lawall wrote:
Quoted 6 lines · Takashi Iwai
Documentation/process/coding-style.rst If you are afraid to mix up your local variable names, you have another · line 335
Quoted 4 lines · Dan Williams
Documentation/process/coding-style.rst +3
-0+Recommended replacements for 'blacklist/whitelist' are: + 'denylist / allowlist' + 'blocklist / passlist'
Alternatively and simply
'peterZ-list / ingoM-list'
as both peterZ and ingoM are Linux specific where is a better place for everyone.
Quoted 29 lines
Quoted 9 lines
I started looking through the tree now and noticed there are lots of patterns like "whitelisted" or "blacklisted". How can the words fit for those? Actually, there are two cases like:
- Foo is blacklisted
- Allow to load the non-whitelisted cardsCurrently I'm replacing the former with "Foo is in denylist", but not
In the denylist?
julia
Quoted 14 lines
sure about the latter case. I thought Kees mentioned about this, but don't remember the proposal...
In anyway, I'm for the action:
Acked-by Takashi Iwai <[email protected]>thanks,
Takashi
_______________________________________________
Ksummit-discuss mailing list
[email protected]
https://lists.linuxfoundation.org/mailman/listinfo/ksummit-discuss
Quoted 11 lines · Takashi Iwai
Documentation/process/coding-style.rst If you are afraid to mix up your local variable names, you have another · line 335
Quoted 4 lines · Dan Williams
Documentation/process/coding-style.rst +3
-0+Recommended replacements for 'blacklist/whitelist' are: + 'denylist / allowlist' + 'blocklist / passlist'I started looking through the tree now and noticed there are lots of patterns like "whitelisted" or "blacklisted". How can the words fit for those? Actually, there are two cases like:
Quoted 6 lines
- Foo is blacklisted
- Allow to load the non-whitelisted cardsCurrently I'm replacing the former with "Foo is in denylist", but not sure about the latter case. I thought Kees mentioned about this, but don't remember the proposal...
Remember these are suggestions for going forwards, not requirements for changing everything. We tend to be a community that likes make work projects because they're easier to do than solving the hard problems, but since we have over 100k occurrences of the various words in the kernel, changing them all would cause massive churn and disrupt forward development, which would cause way more harm than any gain from the change.
James
Quoted 11 lines · Takashi Iwai
Documentation/process/coding-style.rst If you are afraid to mix up your local variable names, you have another · line 335
Quoted 4 lines · Dan Williams
Documentation/process/coding-style.rst +3
-0+Recommended replacements for 'blacklist/whitelist' are: + 'denylist / allowlist' + 'blocklist / passlist'I started looking through the tree now and noticed there are lots of patterns like "whitelisted" or "blacklisted". How can the words fit for those? Actually, there are two cases like:
Quoted 6 lines
- Foo is blacklisted
- Allow to load the non-whitelisted cardsCurrently I'm replacing the former with "Foo is in denylist", but not sure about the latter case. I thought Kees mentioned about this, but don't remember the proposal...
I find that "blocklist" works well as a verb: "foo is blocklisted", "blocklist foo", or in some cases just "block foo" or "deny foo". For the second case, phrasings like "allow loading non-safelisted cards" or "allow loading cards not on the passlist" seem clear.
Quoted 16 lines · On Tue, 14 Jul 2020 06:39:49 +0200, [email protected] wrote:
Quoted 14 lines · Takashi Iwai
Documentation/process/coding-style.rst If you are afraid to mix up your local variable names, you have another · line 335
Quoted 4 lines · Dan Williams
Documentation/process/coding-style.rst +3
-0+Recommended replacements for 'blacklist/whitelist' are: + 'denylist / allowlist' + 'blocklist / passlist'I started looking through the tree now and noticed there are lots of patterns like "whitelisted" or "blacklisted". How can the words fit for those? Actually, there are two cases like:
- Foo is blacklisted
- Allow to load the non-whitelisted cards
Quoted 8 lines
Quoted 3 lines
Currently I'm replacing the former with "Foo is in denylist", but not sure about the latter case. I thought Kees mentioned about this, but don't remember the proposal...
I find that "blocklist" works well as a verb: "foo is blocklisted", "blocklist foo", or in some cases just "block foo" or "deny foo". For the second case, phrasings like "allow loading non-safelisted cards" or "allow loading cards not on the passlist" seem clear.
Yes, that makes sense. I have wished some simple replacement with sed, but it seems that it'd be better to rephrase such texts in anyway.
thanks,
Takashi
Quoted 12 lines · Takashi Iwai
Documentation/process/coding-style.rst If you are afraid to mix up your local variable names, you have another · line 335
Quoted 4 lines · Dan Williams
Documentation/process/coding-style.rst +3
-0+Recommended replacements for 'blacklist/whitelist' are: + 'denylist / allowlist' + 'blocklist / passlist'I started looking through the tree now and noticed there are lots of patterns like "whitelisted" or "blacklisted". How can the words fit for those? Actually, there are two cases like:
Quoted 6 lines
- Foo is blacklisted
- Allow to load the non-whitelisted cardsCurrently I'm replacing the former with "Foo is in denylist", but not sure about the latter case. I thought Kees mentioned about this, but don't remember the proposal...
Hmm. In these cases, we're trying to convey one of two things. A given device/platform/CPU/whatever could be known to be problematic and thus disallowed, or we could have a policy that we generally don't trust hardware but we have specific reason to believe that this particular hardware is okay. After doing a highly scientific sampling of a few cases, some of these are indeed lists and some are not.
If we're going to look for new words for these concepts, perhaps we shouldn't focus on the *list* aspect -- after all, that's just a rather popular implementation detail, but it's not the core concept we're trying to express. As an example case, we have a horrible concept in which some Intel CPUs support a form of memory failure recovery, and there is no enumeration mechanism. Instead, there's a list (sigh). So we could say "your CPU is whitelisted for such-and-such," which at least gets the idea across, but saying "your CPU is allowlisted for such-and-such" seems like a stretch. It's not that we have a policy to allow things on the list -- it's that we think that CPUs not on the list simply don't have the relevant capability.
Here are some brainstormed ideas:
- Such-and-such feature is quirked off. (Or disabled due to a quirk.)
- Your device is not on the known-good list.
- Your device is not known-good. It might work anyway -- to try it,
set such-and-such option.
- Your device is known bad.
- Your device is busted and we think you should pressure the
manufacturer to fix it.
- Your device is too old and no longer supported.
- Seriously, you're trying to use an 80386 on a modern kernel? No
thanks. We think it's neat that you still have one that works, though.
- (Specifically for modules and not part of the Linux kernel tree)disable_autoload instead of blacklist, perhaps?
Part of my point is that we use blacklist and whitelist to mean various things, and I don't think we should try to invent a couple of new catch-all terms to replace them. Perhaps replacing these words could be an opportunity to come up with better descriptions at the same time.
Quoted 4 lines · Dan Williams
Linux maintains a coding-style and its own idiomatic set of terminology. Update the style guidelines to recommend replacements for the terms master/slave and blacklist/whitelist.
Quoted 16 lines
Link http://lore.kernel.org/r/159389297140.2210796.13590142254668787525.stgit@dwillia2-desk3.amr.corp.intel.com open hereAcked-by Randy Dunlap <[email protected]>Acked-by Dave Airlie <[email protected]>Acked-by SeongJae Park <[email protected]>Acked-by James Bottomley <[email protected]>Reviewed-by Mark Brown <[email protected]>Signed-off-by Theodore Ts'o <[email protected]>Signed-off-by Shuah Khan <[email protected]>Signed-off-by Dan Carpenter <[email protected]>Signed-off-by Kees Cook <[email protected]>Signed-off-by Olof Johansson <[email protected]>Signed-off-by Jonathan Corbet <[email protected]>Signed-off-by Chris Mason <[email protected]>Signed-off-by Greg Kroah-Hartman <[email protected]>Signed-off-by Dan Williams <[email protected]>
FWIW,
Quoted 57 lines
---
Changes since v2 [1]:
- Pick up missed sign-offs and acks from Jon, Shuah, and Christian (sorry about missing those earlier).- Reformat the replacement list to make it easier to read.
- Add 'controller' as a suggested replacement (Kees and Mark)
- Fix up the paired term for 'performer' to be 'director' (Kees)
- Collect some new acks, reviewed-by's, and sign-offs for v2.
- Fix up Chris's email
Documentation/process/coding-style.rst | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+)Documentation/process/coding-style.rst +20
-0@@ -319,6 +319,26 @@ 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 and documentation, avoid introducing new usage of +'master / slave' (or 'slave' independent of 'master') and 'blacklist / +whitelist'. + +Recommended replacements for 'master / slave' are: + '{primary,main} / {secondary,replica,subordinate}' + '{initiator,requester} / {target,responder}' + '{controller,host} / {device,worker,proxy}' + 'leader / follower' + 'director / performer' + +Recommended replacements for 'blacklist/whitelist' are: + 'denylist / allowlist' + 'blocklist / passlist' + +Exceptions for introducing new usage is to maintain a userspace ABI/API, +or when updating code for an existing (as of 2020) hardware or protocol +specification that mandates those terms. For new specifications +translate specification usage of the terminology to the kernel coding +standard where possible. 5) Typedefs -----------_______________________________________________
Ksummit-discuss mailing list
[email protected]
https://lists.linuxfoundation.org/mailman/listinfo/ksummit-discuss
Signature · 1 line
Jani Nikula, Intel Open Source Graphics Center
Pavel Machek
NAKQuoted 38 lines · Dan Williams
Linux maintains a coding-style and its own idiomatic set of terminology. Update the style guidelines to recommend replacements for the terms master/slave and blacklist/whitelist.
Link http://lore.kernel.org/r/159389297140.2210796.13590142254668787525.stgit@dwillia2-desk3.amr.corp.intel.com open hereAcked-by Randy Dunlap <[email protected]>Acked-by Dave Airlie <[email protected]>Acked-by SeongJae Park <[email protected]>Acked-by James Bottomley <[email protected]>Reviewed-by Mark Brown <[email protected]>Signed-off-by Theodore Ts'o <[email protected]>Signed-off-by Shuah Khan <[email protected]>Signed-off-by Dan Carpenter <[email protected]>Signed-off-by Kees Cook <[email protected]>Signed-off-by Olof Johansson <[email protected]>Signed-off-by Jonathan Corbet <[email protected]>Signed-off-by Chris Mason <[email protected]>Signed-off-by Greg Kroah-Hartman <[email protected]>Signed-off-by Dan Williams <[email protected]>---
Changes since v2 [1]:
- Pick up missed sign-offs and acks from Jon, Shuah, and Christian (sorry about missing those earlier).- Reformat the replacement list to make it easier to read.
- Add 'controller' as a suggested replacement (Kees and Mark)
- Fix up the paired term for 'performer' to be 'director' (Kees)
- Collect some new acks, reviewed-by's, and sign-offs for v2.
- Fix up Chris's email
Quoted 8 lines
Documentation/process/coding-style.rst | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+)+Recommended replacements for 'blacklist/whitelist' are: + 'denylist / allowlist' + 'blocklist / passlist' + +Exceptions for introducing new usage is to maintain a userspace ABI/API, +or when updating code for an existing (as of 2020) hardware or protocol +specification that mandates those terms. For new specifications +translate specification usage of the terminology to the kernel coding +standard where possible.
Please try to understand how "blacklist" is used in the kernel before suggesting replacements.
NAK.
Pavel
Signature · 2 lines
(english) http://www.livejournal.com/~pavelmachek (cesky, pictures) http://atrey.karlin.mff.cuni.cz/~pavel/picture/horses/blog.html