kubernetes
/
community
mirror of https://github.com/kubernetes/community.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

sig-architecture/naming: Fixup markdownlint warnings 

Signed-off-by: Stephen Augustus <foo@auggie.dev>
This commit is contained in:
Stephen Augustus 2021-09-22 03:05:56 -04:00
parent 941bc0a22b
commit 5ee9f8e5cb
No known key found for this signature in database
GPG Key ID: 5C9566007B24BDA9
4 changed files with 94 additions and 89 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
sig-architecture/naming/language-evaluation-framework.md
View File

@ -15,7 +15,6 @@ First-order concerns are language where harm is egregious, overt, and clearly pr
Answer all questions for each term evaluated.
When complete, consider questions answered in the affirmative: in general, the more questions answered “yes” or “possibly”, the more likely it is that the language in question needs to be replaced.
If any first-order concerns are a “yes”, replace the language.
@ -62,7 +61,6 @@ Examples include “KILL” commands in Unix systems.
Examples include “marshal/unmarshal”.
### Third-order concerns
Third-order concerns are characterized by:
@ -73,7 +71,6 @@ Third-order concerns are characterized by:
- Idiomatic: Is language unclear to someone outside a specific culture?
#### Is the term evocative instead of descriptive?
Examples include “PetSet” (evocative) versus “StatefulSet” (descriptive).
@ -96,7 +93,6 @@ We recommend:
- Expecting that some of your work will need re-evaluation at a later date
- Openness to updating language as readers and cultures change
### Dealing with trolls
In the handful of months since this work began, both Kubernetes as a whole and WG Naming have dealt with a number of issues and comments from trolls. We anticipate that anyone using this document to guide their own work will receive the same kind of attention.

6
sig-architecture/naming/recommendations/000-template.md
View File

@ -1,17 +1,19 @@
# Recommendation: replace Old Term
**Last Updated**: date PR was last updated, e.g. 2020-10-16
**Status:** Accepted
## Suggested Alternatives
Replacements:
- `new term`: description of where this term is applicable.
<any additional terms>
- Make the recommendation the title of the PR. For example: "Change default repository branches from 'master' to 'main'"
- Provide a brief, 1-3 sentence summary of the reasoning for this change
- Provide alternate recommendation(s) if needed
- Provide alternate recommendation(s), if needed
## Context
@ -24,3 +26,5 @@ Provide any research, links to PR(s) from the Kubernetes project or other commun
## Impact
Link to the results of a [Hound](https://cs.k8s.io/) keyword search. What impact will this change create?
[language-evaluation-framework]: /sig-architecture/naming/language-evaluation-framework.md

44
sig-architecture/naming/recommendations/001-master-control-plane.md
View File

@ -15,6 +15,7 @@ when talking about individual components or the roles they serve.
## Suggested Alternatives
### Control Plane
- e.g. "The control plane is the set of all components responsible for
controlling a kubernetes cluster"
- e.g. "The control plane is the thing that can be communicated with in order to
@ -26,19 +27,26 @@ when talking about individual components or the roles they serve.
other"
- instance, e.g. "we are going to create multiple control plane apiserver
instances; we will talk only to this specific instance"
- <component name>, e.g. "we will simulate an etcd fault by running this
- <component-name>, e.g. "we will simulate an etcd fault by running this
command on instances where etcd is hosted"
### Control Plane Node
- "A node that hosts components that are part of the control plane", e.g.
- https://github.com/kubernetes/enhancements/tree/master/keps/sig-cluster-lifecycle/kubeadm/2067-rename-master-label-taint
- "A node that hosts components that are part of the control plane"
Examples:
- https://git.k8s.io/enhancements/keps/sig-cluster-lifecycle/kubeadm/2067-rename-master-label-taint
- https://github.com/kubernetes/kubernetes/pull/95053/files#diff-b4f6256abfd125f7ce69fd1ba1eaf595R886
- Also relevant for terms other than node, e.g. control plane machine, control
plane host, control plane vm, control plane instance, e.g.
- Also relevant for terms other than node e.g., "control plane machine",
"control plane host", "control plane VM", "control plane instance"
Example:
- https://github.com/kubernetes/kubernetes/blob/99cc89b7da32d9c06916deb50b27fdb46934b777/cluster/gce/gci/master-helper.sh#L33
should be `create-control-plane-instance`
### Leader
- e.g. "The leader is the winner of a leader election"
- When using an adjective instead of a noun to describe this concept, there is
likely a more specific term:
@ -47,6 +55,7 @@ other"
- primary/replica
## Other Considerations
- if the api field, flag, code, command etc. uses the literal word 'master' and
cannot be immediately changed or has no alternative available, use this word
only in direct reference to the code item
@ -71,11 +80,13 @@ control plane?
Master raises first-order concerns according to [our language evaluation
framework][framework]:
- it is overtly racist (ref: [django][django-master], [Drupal][drupal-master],
[IETF][ietf-master],
[Google][https://developers.google.com/style/word-list#master])
Master also raises third-order concerns:
- within kubernetes it is used to represent a variety of overlapping or
unrelated concepts (see the variety of suggested alternatives)
- one class of usage represents a set of false assumptions:
@ -85,6 +96,7 @@ Master also raises third-order concerns:
on certain ports, etc.)
Prior discussions:
- [kubernetes-wg-naming@ - proposal: master/slave
alternatives][wg-naming-thread]
- [kubernetes-sig-architecture@ - Re: the way we discuss control plane
@ -92,22 +104,20 @@ Prior discussions:
## Consequences
TODO
## TODO
- hound search that approximates excluding some master-branch-in-docs
references, and references in vendor/:
https://cs.k8s.io/?q=master%5B%5E%2F%5D&i=nope&files=%5E%5B%5Ev%5D&repos=
- references to master in test/e2e/framework
(https://github.com/kubernetes/kubernetes/issues/94901)
- references to master in test/integration
(https://github.com/kubernetes/kubernetes/issues/94900)
- [hound search](https://cs.k8s.io/?q=master%5B%5E%2F%5D&i=nope&files=%5E%5B%5Ev%5D&repos=)
that approximates excluding some master-branch-in-docs references, and
references in `vendor/`
- [references to "master" in `test/e2e/framework`](https://github.com/kubernetes/kubernetes/issues/94901)
- [references to "master" in `test/integration`](https://github.com/kubernetes/kubernetes/issues/94900)
- known names/flags/fields/labels/annotations that may take time to change
- `"system:masters"` aka
- `"system:masters"` AKA
[k8s.io/apiserver/pkg/authentication/user.SystemPrivilegedGroup][system-privileged-group]
- `node-role.kubernetes.io/master` (tracking issue for KEP
https://github.com/kubernetes/enhancements/issues/2067)
- `node-role.kubernetes.io/master`
([enhancement tracking issue](https://github.com/kubernetes/enhancements/issues/2067))
- `--endpoint-reconciler-type master-count`
- probably more
- ...probably more
[architecture]: https://git.k8s.io/community/contributors/design-proposals/architecture/architecture.md#architecture
[wg-naming-thread]: https://groups.google.com/g/kubernetes-wg-naming/c/VqrBCdUHdPc

69
sig-architecture/naming/recommendations/002-blacklist-whitelist-allowlist-denylist.md
View File

@ -6,7 +6,6 @@
## Suggested Alternatives
Replacements:
- `allowlist/denylist`
## Context
@ -15,77 +14,73 @@ The underlying assumption of the whitelist/blacklist metaphor is that white = go
From a technical communication perspective, using whitelist/blacklist as a naming convention applies metaphor (and, in turn, unintended meaning) when it isn’t needed. Descriptive words like allowlist/denylist enhance understanding. Allowlist/denylist, or simply allowed/denied as an entity prefix, are also easier to localize.
This term measures up against the evaluation framework as follows:
**First-order concerns**:
### First-order concerns
In short: is the term overt or identity specific? **Not quite.**
* Is the term overtly racist? **Maybe**. See [this article](https://www.ncbi.nlm.nih.gov/pmc/articles/PMC6148600/) for more.
* Is the term overtly sexist, transphobic, or pejorative about a gender identity? **No**
* Is the term overtly ableist, or pejorative to neurodiverse or disabled people? **No**
* Is the term overtly homophobic? **No**
- Is the term overtly racist? **Maybe**. See [this article](https://www.ncbi.nlm.nih.gov/pmc/articles/PMC6148600/) for more.
- Is the term overtly sexist, transphobic, or pejorative about a gender identity? **No**
- Is the term overtly ableist, or pejorative to neurodiverse or disabled people? **No**
- Is the term overtly homophobic? **No**
**Second-order concerns**:
### Second-order concerns
In short: is the term ambigously harmful, or is it harmful but not to a specific identity? **Yes**. Once again, see [this article](https://www.ncbi.nlm.nih.gov/pmc/articles/PMC6148600/)
In particular, see the following pull-quote:
> In this context, it is worth examining the origins of the term “blacklist” from the Douglas Harper Etymology Dictionary, which states that its origin and history is:
> > n.
> > also black-list, black list, “list of persons who have incurred suspicion,” 1610s, from black (adj.), here indicative of disgrace, censure, punishment (attested from 1590s, in black book) + list (n.). Specifically of employers’ list of workers considered troublesome (usually for union activity) is from 1888. As a verb, from 1718. Related: Blacklisted; blacklisting. [32]
>
>> n.
>>
>> also black-list, black list, “list of persons who have incurred suspicion,” 1610s, from black (adj.), here indicative of disgrace, censure, punishment (attested from 1590s, in black book) + list (n.). Specifically of employers’ list of workers considered troublesome (usually for union activity) is from 1888. As a verb, from 1718. Related: Blacklisted; blacklisting. [32]
>
> It is notable that the first recorded use of the term occurs at the time of mass enslavement and forced deportation of Africans to work in European-held colonies in the Americas.
While it is not directly attacking specific identities, in other context it does have negative connotations.
* Is the term violent? **Partially**
* Is the term militaristic? **No**
- Is the term violent? **Partially**
- Is the term militaristic? **No**
**Third-order concerns**
* Is the term evocative instead of descriptive? **Yes**
* Is the term ambiguous? **Yes. As mentioned in the above description, "black" and "white" have different meanings in different cultures.**
### Third-order concerns
- Is the term evocative instead of descriptive? **Yes**
- Is the term ambiguous? **Yes. As mentioned in the above description, "black" and "white" have different meanings in different cultures.**
## Precedents
* [“Blacklists” and “whitelists”: a salutary warning concerning the prevalence of racist language in discussions of predatory publishing](https://www.ncbi.nlm.nih.gov/pmc/articles/PMC6148600/)
- [“Blacklists” and “whitelists”: a salutary warning concerning the prevalence of racist language in discussions of predatory publishing](https://www.ncbi.nlm.nih.gov/pmc/articles/PMC6148600/)
* [IETF Network Working Group: Terminology, Power and Oppressive Language](https://tools.ietf.org/id/draft-knodel-terminology-00.html)
- [IETF Network Working Group: Terminology, Power and Oppressive Language](https://tools.ietf.org/id/draft-knodel-terminology-00.html)
* [Android issue changing these terms (screenshot)](https://9to5google.com/wp-content/uploads/sites/4/2020/06/android-aosp-allowlist-explanation.png)
- [Android issue changing these terms (screenshot)](https://9to5google.com/wp-content/uploads/sites/4/2020/06/android-aosp-allowlist-explanation.png)
* [Twitter's language changes](https://www.cnet.com/news/twitter-engineers-replace-racially-loaded-tech-terms-like-master-slave/)
- [Twitter's language changes](https://www.cnet.com/news/twitter-engineers-replace-racially-loaded-tech-terms-like-master-slave/)
## Impact
The majority of uses of blacklist and whitelist occur in `/vendor` directories.
* [Hound search - blacklist](https://cs.k8s.io/?q=blacklist&i=nope&files=&repos=)
* [Hound search - whitelist](https://cs.k8s.io/?q=whitelist&i=nope&files=&repos=)
- [Hound search - blacklist](https://cs.k8s.io/?q=blacklist&i=nope&files=&repos=)
- [Hound search - whitelist](https://cs.k8s.io/?q=whitelist&i=nope&files=&repos=)
If we exclude these, areas for replacement narrow. Many repositories have relatively minor uses outside `/vendor` paths, but the following are significant:
* [kubernetes/kops](https://github.com/kubernetes/kops/): Contains breaking changes (`-whitelisted-healthcheck-cidr` flag, among other uses). Contains uses both in documentation & code.
* [kubernetes/test-infra](https://github.com/kubernetes/test-infra/): Used mainly in relation to Prow.
* [kubernetes/kubernetes](https://github.com/kubernetes/kubernetes/): Contains many non-problematic uses of blacklist, and many potentially breaking change uses of whitelist.
* [kubernetes/api](https://github.com/kubernetes/api/): Used mainly in comments/documentation.
* [kubernetes/cloud-provider-openstack](https://github.com/kubernetes/cloud-provider-openstack/blob/master/docs/keystone-auth/using-auth-data-synchronization.md): Contains breaking changes (config options). See linked documentation.
* [kubernetes/ingress-ngnix](https://github.com/kubernetes/ingress-nginx/): Contains breaking changes (the `ipwhitelist` package). `kubernetes/ingress-gce` contains similar changes required.
* [kubernetes-sigs/node-feature-discovery](https://github.com/kubernetes-sigs/node-feature-discovery/blob/master/docs/advanced/worker-commandline-reference.md): Contains breaking changes (see linked file, `--label-whitelist=<pattern>` flag).
* [kubernetes/website](https://github.com/kubernetes/website/): Many uses in documentation.
* [kubernetes-sigs/kubespray](https://github.com/kubernetes-sigs/kubespray): `callback_whitelist`
* [kubernetes-sigs/reference-docs](https://github.com/kubernetes-sigs/reference-docs): Many uses in docs (`description`) fields.
- [kubernetes/kops](https://github.com/kubernetes/kops/): Contains breaking changes (`-whitelisted-healthcheck-cidr` flag, among other uses). Contains uses both in documentation & code.
- [kubernetes/test-infra](https://github.com/kubernetes/test-infra/): Used mainly in relation to Prow.
- [kubernetes/kubernetes](https://github.com/kubernetes/kubernetes/): Contains many non-problematic uses of blacklist, and many potentially breaking change uses of whitelist.
- [kubernetes/api](https://github.com/kubernetes/api/): Used mainly in comments/documentation.
- [kubernetes/cloud-provider-openstack](https://github.com/kubernetes/cloud-provider-openstack/blob/master/docs/keystone-auth/using-auth-data-synchronization.md): Contains breaking changes (config options). See linked documentation.
- [kubernetes/ingress-nginx](https://github.com/kubernetes/ingress-nginx/): Contains breaking changes (the `ipwhitelist` package). `kubernetes/ingress-gce` contains similar changes required.
- [kubernetes-sigs/node-feature-discovery](https://github.com/kubernetes-sigs/node-feature-discovery/blob/master/docs/advanced/worker-commandline-reference.md): Contains breaking changes (see linked file, `--label-whitelist=<pattern>` flag).
- [kubernetes/website](https://github.com/kubernetes/website/): Many uses in documentation.
- [kubernetes-sigs/kubespray](https://github.com/kubernetes-sigs/kubespray): `callback_whitelist`
- [kubernetes-sigs/reference-docs](https://github.com/kubernetes-sigs/reference-docs): Many uses in docs (`description`) fields.
In addition to the above, there are multiple repos which use either term once. `kubernetes/community` also contains uses, mainly in meeting notes.
Due to the nature of these changes, we recommend the following:
1. Pursue changes **outside** of `/vendor` directories and other imported packages. (Scope changes to our own code)