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. 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. 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. 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”. Examples include “marshal/unmarshal”.
### Third-order concerns ### Third-order concerns
Third-order concerns are characterized by: 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? - Idiomatic: Is language unclear to someone outside a specific culture?
#### Is the term evocative instead of descriptive? #### Is the term evocative instead of descriptive?
Examples include “PetSet” (evocative) versus “StatefulSet” (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 - Expecting that some of your work will need re-evaluation at a later date
- Openness to updating language as readers and cultures change - Openness to updating language as readers and cultures change
### Dealing with trolls ### 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. 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 # Recommendation: replace Old Term
**Last Updated**: date PR was last updated, e.g. 2020-10-16 **Last Updated**: date PR was last updated, e.g. 2020-10-16
**Status:** Accepted **Status:** Accepted
## Suggested Alternatives ## Suggested Alternatives
Replacements: Replacements:
- `new term`: description of where this term is applicable. - `new term`: description of where this term is applicable.
<any additional terms> <any additional terms>
- Make the recommendation the title of the PR. For example: "Change default repository branches from 'master' to 'main'" - 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 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 ## Context
@ -24,3 +26,5 @@ Provide any research, links to PR(s) from the Kubernetes project or other commun
## Impact ## Impact
Link to the results of a [Hound](https://cs.k8s.io/) keyword search. What impact will this change create? 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 ## Suggested Alternatives
### Control Plane ### Control Plane
- e.g. "The control plane is the set of all components responsible for - e.g. "The control plane is the set of all components responsible for
controlling a kubernetes cluster" controlling a kubernetes cluster"
- e.g. "The control plane is the thing that can be communicated with in order to - 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" other"
- instance, e.g. "we are going to create multiple control plane apiserver - instance, e.g. "we are going to create multiple control plane apiserver
instances; we will talk only to this specific instance" 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" command on instances where etcd is hosted"
### Control Plane Node ### 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 - 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 - https://github.com/kubernetes/kubernetes/blob/99cc89b7da32d9c06916deb50b27fdb46934b777/cluster/gce/gci/master-helper.sh#L33
should be `create-control-plane-instance` should be `create-control-plane-instance`
### Leader ### Leader
- e.g. "The leader is the winner of a leader election" - 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 - When using an adjective instead of a noun to describe this concept, there is
likely a more specific term: likely a more specific term:
@ -47,6 +55,7 @@ other"
- primary/replica - primary/replica
## Other Considerations ## Other Considerations
- if the api field, flag, code, command etc. uses the literal word 'master' and - 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 cannot be immediately changed or has no alternative available, use this word
only in direct reference to the code item only in direct reference to the code item
@ -71,11 +80,13 @@ control plane?
Master raises first-order concerns according to [our language evaluation Master raises first-order concerns according to [our language evaluation
framework][framework]: framework][framework]:
- it is overtly racist (ref: [django][django-master], [Drupal][drupal-master], - it is overtly racist (ref: [django][django-master], [Drupal][drupal-master],
[IETF][ietf-master], [IETF][ietf-master],
[Google][https://developers.google.com/style/word-list#master]) [Google][https://developers.google.com/style/word-list#master])
Master also raises third-order concerns: Master also raises third-order concerns:
- within kubernetes it is used to represent a variety of overlapping or - within kubernetes it is used to represent a variety of overlapping or
unrelated concepts (see the variety of suggested alternatives) unrelated concepts (see the variety of suggested alternatives)
- one class of usage represents a set of false assumptions: - one class of usage represents a set of false assumptions:
@ -85,6 +96,7 @@ Master also raises third-order concerns:
on certain ports, etc.) on certain ports, etc.)
Prior discussions: Prior discussions:
- [kubernetes-wg-naming@ - proposal: master/slave - [kubernetes-wg-naming@ - proposal: master/slave
alternatives][wg-naming-thread] alternatives][wg-naming-thread]
- [kubernetes-sig-architecture@ - Re: the way we discuss control plane - [kubernetes-sig-architecture@ - Re: the way we discuss control plane
@ -92,22 +104,20 @@ Prior discussions:
## Consequences ## Consequences
TODO ## TODO
- hound search that approximates excluding some master-branch-in-docs - [hound search](https://cs.k8s.io/?q=master%5B%5E%2F%5D&i=nope&files=%5E%5B%5Ev%5D&repos=)
references, and references in vendor/: that approximates excluding some master-branch-in-docs references, and
https://cs.k8s.io/?q=master%5B%5E%2F%5D&i=nope&files=%5E%5B%5Ev%5D&repos= references in `vendor/`
- references to master in test/e2e/framework - [references to "master" in `test/e2e/framework`](https://github.com/kubernetes/kubernetes/issues/94901)
(https://github.com/kubernetes/kubernetes/issues/94901) - [references to "master" in `test/integration`](https://github.com/kubernetes/kubernetes/issues/94900)
- 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 - 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] [k8s.io/apiserver/pkg/authentication/user.SystemPrivilegedGroup][system-privileged-group]
- `node-role.kubernetes.io/master` (tracking issue for KEP - `node-role.kubernetes.io/master`
https://github.com/kubernetes/enhancements/issues/2067) ([enhancement tracking issue](https://github.com/kubernetes/enhancements/issues/2067))
- `--endpoint-reconciler-type master-count` - `--endpoint-reconciler-type master-count`
- probably more - ...probably more
[architecture]: https://git.k8s.io/community/contributors/design-proposals/architecture/architecture.md#architecture [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 [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 ## Suggested Alternatives
Replacements:
- `allowlist/denylist` - `allowlist/denylist`
## Context ## 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. 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: 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.** 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 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 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 ableist, or pejorative to neurodiverse or disabled people? **No**
* Is the term overtly homophobic? **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 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 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: > 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. >> 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] >> 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. > 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. While it is not directly attacking specific identities, in other context it does have negative connotations.
* Is the term violent? **Partially** - Is the term violent? **Partially**
* Is the term militaristic? **No** - Is the term militaristic? **No**
**Third-order concerns** ### 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.**
- 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 ## 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 ## Impact
The majority of uses of blacklist and whitelist occur in `/vendor` directories. 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 - 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 - 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: 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/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/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/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/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/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/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-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/website](https://github.com/kubernetes/website/): Many uses in documentation.
* [kubernetes-sigs/kubespray](https://github.com/kubernetes-sigs/kubespray): `callback_whitelist` - [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-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. 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: 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) 1. Pursue changes **outside** of `/vendor` directories and other imported packages. (Scope changes to our own code)