From f24db157874395b228000e0209b366b79dff4a95 Mon Sep 17 00:00:00 2001 From: Stephen Augustus Date: Mon, 9 Aug 2021 14:08:06 -0400 Subject: governance: Dissolution of WG Naming Includes transfer of existing documentation to SIG Arch Signed-off-by: Stephen Augustus --- archive/wg-naming/OWNERS | 8 ++ archive/wg-naming/README.md | 87 +++++++++++++++ archive/wg-naming/governance.md | 85 +++++++++++++++ .../naming/language-evaluation-framework.md | 118 ++++++++++++++++++++ .../naming/recommendations/000-template.md | 26 +++++ .../recommendations/001-master-control-plane.md | 119 +++++++++++++++++++++ .../002-blacklist-whitelist-allowlist-denylist.md | 94 ++++++++++++++++ sig-architecture/naming/workflow.md | 92 ++++++++++++++++ wg-naming/OWNERS | 8 -- wg-naming/README.md | 87 --------------- wg-naming/governance.md | 85 --------------- wg-naming/language-evaluation-framework.md | 118 -------------------- wg-naming/recommendations/000-template.md | 26 ----- .../recommendations/001-master-control-plane.md | 119 --------------------- .../002-blacklist-whitelist-allowlist-denylist.md | 94 ---------------- wg-naming/workflow.md | 92 ---------------- 16 files changed, 629 insertions(+), 629 deletions(-) create mode 100644 archive/wg-naming/OWNERS create mode 100644 archive/wg-naming/README.md create mode 100644 archive/wg-naming/governance.md create mode 100644 sig-architecture/naming/language-evaluation-framework.md create mode 100644 sig-architecture/naming/recommendations/000-template.md create mode 100644 sig-architecture/naming/recommendations/001-master-control-plane.md create mode 100644 sig-architecture/naming/recommendations/002-blacklist-whitelist-allowlist-denylist.md create mode 100644 sig-architecture/naming/workflow.md delete mode 100644 wg-naming/OWNERS delete mode 100644 wg-naming/README.md delete mode 100644 wg-naming/governance.md delete mode 100644 wg-naming/language-evaluation-framework.md delete mode 100644 wg-naming/recommendations/000-template.md delete mode 100644 wg-naming/recommendations/001-master-control-plane.md delete mode 100644 wg-naming/recommendations/002-blacklist-whitelist-allowlist-denylist.md delete mode 100644 wg-naming/workflow.md diff --git a/archive/wg-naming/OWNERS b/archive/wg-naming/OWNERS new file mode 100644 index 00000000..b85dde17 --- /dev/null +++ b/archive/wg-naming/OWNERS @@ -0,0 +1,8 @@ +# See the OWNERS docs at https://go.k8s.io/owners + +reviewers: + - wg-naming-leads +approvers: + - wg-naming-leads +labels: + - wg/naming diff --git a/archive/wg-naming/README.md b/archive/wg-naming/README.md new file mode 100644 index 00000000..785b0d2b --- /dev/null +++ b/archive/wg-naming/README.md @@ -0,0 +1,87 @@ + +# Naming Working Group + + +## Stakeholder SIGs +* SIG Architecture +* SIG Contributor Experience +* SIG Docs + +## Meetings +* Regular WG Meeting: [Mondays at 10:30 PT (Pacific Time)](https://zoom.us/j/91522666403?pwd=WnRSNlNhNXhDWkR2ZU9ydGpsNWxtZz09) (monthly - second Monday of month). [Convert to your timezone](http://www.thetimezoneconverter.com/?t=10:30&tz=PT%20%28Pacific%20Time%29). + * [Meeting notes and Agenda](https://bit.ly/k8s-wg-naming-agenda). + * [Meeting recordings](https://www.youtube.com/playlist?list=PL69nYSiGNLP3BrAtDHyr8KTUfhBhCG7CD). + +## Organizers + +* Celeste Horgan (**[@celestehorgan](https://github.com/celestehorgan)**), CNCF +* Jaice Singer DuMars (**[@jdumars](https://github.com/jdumars)**), Apple +* Stephen Augustus (**[@justaugustus](https://github.com/justaugustus)**), Cisco + +## Emeritus Organizers + +* Zach Corleissen (**[@zacharysarah](https://github.com/zacharysarah)**) + +## Contact +- Slack: [#wg-naming](https://kubernetes.slack.com/messages/wg-naming) +- [Mailing list](https://groups.google.com/forum/#!forum/kubernetes-wg-naming) +- [Open Community Issues/PRs](https://github.com/kubernetes/community/labels/wg%2Fnaming) +- Steering Committee Liaison: Bob Killen (**[@mrbobbytables](https://github.com/mrbobbytables)**) + + +**The following section will be reworked and formalized as a charter once the +Working Group has been approved by the Steering Committee.** + +## Goals + +- Evaluate language and naming choices within the Kubernetes project, with + a specific initial focus of: + - Removing barriers to contribution and adoption by replacing harmful language with neutral terms whenever possible, including but not limited to language linked to racism, sexism, homophobia, transphobia, ableism, or discrimination against any protected or historically underrepresented group. + - Improving clarity of codebases and documentation by replacing idioms, + metaphors and slang specific to the English language +- Create a list of harmful terms with proposed replacements +- Define how any member of the Kubernetes project can + recommend language, how others can evaluate that proposal, and how to + implement replacements across all codebases. + - Provide an easily findable location for language recommendations and + follow-up issues, similar to an architectural decision record + - Define long-term ownership of this process +- Work with stakeholder SIGs to implement the changes recommended. We + anticipate the following: + - Provide stakeholder SIGs with guidance on naming, language conventions, and + processes + - Collaborate with SIG Architecture and other stakeholders on an + implementation timeline and strategies for dealing with follow-up issues + from renaming, like deprecations + - Collaborate with SIG Docs and SIG Contributor Experience on documenting + language recommendations and processes + - Work with the Code of Conduct Committee to add code architecture to the COC + +## Dissolution Criteria + +Once the Kubernetes community has: + +- A process in place to evaluate language changes on an ongoing basis +- A binding list of terms to avoid in codebases across the project +- A timeline on which to replace component names in the kubernetes/kubernetes + codebase +- Defined long-term ownership of the policies and processes this WG creates + +this WG will dissolve. + +## Post-formation Discussion Points + +- Discuss appropriate process for branch renaming with GitHub Administration + subproject (SIG ContribEx) +- Work with the Code of Conduct Committee to add code architecture to the COC +- A timeline on which to replace component names in the kubernetes/kubernetes +- Clarify that WG should not dissolve until after changes have been made + + diff --git a/archive/wg-naming/governance.md b/archive/wg-naming/governance.md new file mode 100644 index 00000000..5f15a42f --- /dev/null +++ b/archive/wg-naming/governance.md @@ -0,0 +1,85 @@ +# WG Naming governance + +## Uphold project values + +WG Naming upholds the Kubernetes project's [core values](/values.md). + +### Inclusive is better than exclusive + +> Broadly successful and useful technology requires different perspectives and skill sets which can only be heard in a welcoming and respectful environment. + +This document covers some specific ways in which WG Naming offers respect and welcome. + +> Our community shows respect for the time and effort put into a discussion regardless of where a contributor is on their growth path. + +Like other SIGs and working groups, WG Naming has prerequisite skills, training, and experience that are necessary for meaningful contribution. For example: + + - Education or professional experience in dismantling systemic discrimination + - Demonstrable familiarity with current antidiscrimination resources + - A track record of supporting inclusion in the Kubernetes project + +WG Naming has many stakeholders, with many people eager to add their voices. WG Naming invites folks who are new to antiracism or inclusive language, and folks less experienced with frameworks of discrimination to participate by observing and learning. WG Naming invites contributors who meet prerequisites to contribute within the scope of WG Naming’s goals. + +### Resources for antidiscrimination + +- https://developers.google.com/style/inclusive-documentation +- https://www.antiracismresources.info/#online-resources +- _How to Be An Antiracist_, Ibrahim X. Kendi +- _So You Want to Talk About Race_, Ijeoma Oluo + +### Scope of discussion + +WG Naming actively moderates discussion for speech that affirms the humanity of underrepresented minorities and affirms their ongoing experience of discrimination. For example: specific suggestions for replacement terms are welcome. Disagreement over the presence and impact of racism is not welcome. + +## Follow the community code of conduct + +Like all WGs and SIGs, WG Naming expects contributors to follow the [Kubernetes Code of Conduct (CoC)]. + +We raise this section’s topics as potential blockers to the work of WG Naming, since experience has shown they are a common and detrimental response. + +From the CoC: + +> Examples of unacceptable behavior by participants include: +> +> - Personal attacks +> - Trolling or insulting/derogatory comments + +**Note:** the CoC governs conduct, not intent. WG Naming leads may refer unacceptable conduct to the Code of Conduct Committee regardless of professed intent. + +[Kubernetes Code of Conduct (CoC)]: /code-of-conduct.md + +### Personal attacks + +Personal attacks include denying or questioning the lived experience of underrepresented minorities. For example: arguing that problematic terms "aren't racist", or any statements reducible or equivalent to "all lives matter". + +### Trolling + +Trolling includes: + +- [Concern trolling](https://en.wiktionary.org/wiki/concern_troll) + +- Derailing behavior + + Behavior that distracts from WG Naming's purpose or attempts to redirect participants' energy into minutiae or unrelated topics or goals. + + For example: + - insisting that previous decisions be re-argued + - insisting that WG Naming can take no action until all possible inequities are addressed + +- [Sea lioning](https://www.forbes.com/sites/marshallshepherd/2019/03/07/sealioning-is-a-common-trolling-tactic-on-social-media-what-is-it/) + + Endless demands for evidence; refusing to accept or acknowledge peer-reviewed scientific research; insisting that one's ignorance, whether real or feigned, be satisfied by the WG group to an individual's satisfaction. + + See the original Wondermark comic: [sea lions](http://wondermark.com/1k62/) + +- [Brigading](https://en.wikipedia.org/wiki/Vote_brigading) + + Attempting to overrepresent a viewpoint through participation bias + +## Deviations from [sig-governance] + +WG Naming leads may close or end meetings at their discretion to shut down trolling or protect the safety of community members. + +WG Naming [restricts the scope of discussion](#scope-of-discussion). + +[sig-governance]: /committee-steering/governance/sig-governance.md diff --git a/sig-architecture/naming/language-evaluation-framework.md b/sig-architecture/naming/language-evaluation-framework.md new file mode 100644 index 00000000..959e9270 --- /dev/null +++ b/sig-architecture/naming/language-evaluation-framework.md @@ -0,0 +1,118 @@ + +# A framework for evaluating harmful language + +## About + +The language evaluation framework is a guidance document developed by the Kubernetes Naming Working Group. It outlines a structured framework for evaluating language and terminology for harm to the community. This enables the community to navigate divisive conversations with a measure of clarity. + +The framework was created for an open source technology project. The framework may be applicable to other fields as well. + +## Using the framework + +The framework is divided into three sections: first-, second-, and third-order concerns, ranked in order of potential harm to the community. + +First-order concerns are language where harm is egregious, overt, and clearly problematic. Second-order concerns are language which is problematic but with a less definite impact. Third-order concerns indicate language that could use improvement but does no demonstrable harm. + +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. + +If a significant number of second- or third- order concerns are a “yes”, strongly consider replacing the language. + +This framework is intentionally non-prescriptive. The intention in this work is to reduce harm for the community; let harm reduction guide your decisions. + +### First-order concerns + +First-order concerns are characterized by: + +- Overtness: regardless of its use in the context of code or technology, there is little to no ambiguity outside of technology as to whether the language in question indicates harm +- Identity-specificity: language in question specifically unambiguously identifies a group of people + +#### Is the term overtly racist? + +Examples include “master/slave”. + +#### Is the term overtly sexist, transphobic, or pejorative about a gender identity? + +Examples do _not_ include “transclusion” of dependencies, or “binary” operators. + +#### Is the term overtly ableist, or pejorative to neurodiverse or disabled people + +Examples include performing “sanity checks”. + +#### Is the term overtly homophobic? + +Examples do not include “homogenizing” or “homogenous” data. + +### Second-order concerns + +Second-order concerns are characterized by: + +- Ambiguity: outside the context of code or technology, language might have connotations related to harmful scenarios like war, militarization, or policing, but the actual etymology of the term is not related to harm of a specific identity +- Lack of specific identity: concerns in this category do not target specific identities, or do so in a non-overt way + +#### Is the term violent? + +Examples include “KILL” commands in Unix systems. + +#### Is the term militaristic? + +Examples include “marshal/unmarshal”. + + +### Third-order concerns + +Third-order concerns are characterized by: + +- Clarity: is the language in use a metaphor that could be described more precisely using different words? + +- Anthropomorphism: does language unnecessarily humanize components or processes? + +- Idiomatic: Is language unclear to someone outside a specific culture? + + +#### Is the term evocative instead of descriptive? + +Examples include “PetSet” (evocative) versus “StatefulSet” (descriptive). + +#### Is the term ambiguous? + +Examples include the use of ABORT/STOP/KILL in Unix-like systems, where they map to specific behaviors, versus general usage in programming languages, where they map to different behaviors or are used interchangeably. + +## Footnotes + +### Changes over time + +In general, strong democratic societies become more progressive and accepting as time passes. This is a feature, not a bug. + +As a result, terms that were once deemed acceptable may, at some future point, be deemed unacceptable. + +We recommend: + +- Placing a date at the top of any documents/recommendations related to naming, language inclusivity, or harm reduction +- 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. + +In Kubernetes we mostly encounter [sea lions](http://wondermark.com/1k62/) (concern trolls), who seek to legitimize debate over false concerns in order to use up contributors' energy and time. + +We work with our GitHub and other moderation teams to shut down trolling behavior at the source and remove trolling content. + +In cases where it’s unclear whether the poster is a legitimate user or a troll, we direct the work back to them: because they’re clearly “legitimately interested” in this topic, we ask them to join us in the WG Naming mailing list, drafting a formal suggestion (attached to an email address and identity we can track) and suggesting replacement terminology. Most trolls do not want to put in the effort. + +Rather than be discouraged by trolls, consider it a heartening sign that you are engaged in meaningful work. + +### Kudos + +This work would not have come into shape without referencing the following resources freely available online. We thank the authors of these original documents for helping guide our thoughts on the topic: + +- [APA Style Guide: General Principles for reducing bias](https://apastyle.apa.org/style-grammar-guidelines/bias-free-language/general-principles) +- [Shopify Polaris Content Guidelines: Descriptive vs. Evocative names](https://polaris.shopify.com/content/naming#section-descriptive-vs-evocative-names) +- [CNET: Twitter engineers: out with the old words...](https://www.cnet.com/news/twitter-engineers-replace-racially-loaded-tech-terms-like-master-slave/) diff --git a/sig-architecture/naming/recommendations/000-template.md b/sig-architecture/naming/recommendations/000-template.md new file mode 100644 index 00000000..9779d80c --- /dev/null +++ b/sig-architecture/naming/recommendations/000-template.md @@ -0,0 +1,26 @@ +# 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. + + +- 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 + +## Context + +- Provide information about the recommendation. Why does this proposal matter? Who does it affect? How will it help? How does it evaluate against the [language-evaluation-framework]? + +## Precedents + +Provide any research, links to PR(s) from the Kubernetes project or other communities, standards body documents, or style guides that provide precedent for this decision. + +## Impact + +Link to the results of a [Hound](https://cs.k8s.io/) keyword search. What impact will this change create? diff --git a/sig-architecture/naming/recommendations/001-master-control-plane.md b/sig-architecture/naming/recommendations/001-master-control-plane.md new file mode 100644 index 00000000..038ca252 --- /dev/null +++ b/sig-architecture/naming/recommendations/001-master-control-plane.md @@ -0,0 +1,119 @@ +# Recommendation: master -> control plane + +**Last Updated**: 2020-10-16 + +**Status**: Accepted + +## Recommendation + +Within the Kubernetes codebase, the term “master” is often used in reference to +[the kubernetes control plane][architecture], either as a whole or to some +subset of the components within. We recommend **control plane** to refer to the +set of components as a whole. We recommend **context-specific alternatives** +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 + control a kubernetes cluster" +- If it matters which specific component(s) or component instance is being + communicated with, be specific: + - endpoint, e.g. "we don't care whether a load balancer, apiserver, or other + component is behind this endpoint; we will talk only to this endpoint and no +other" + - instance, e.g. "we are going to create multiple control plane apiserver + instances; we will talk only to this specific instance" + - , 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 + - 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. + - 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: + - active/passive, e.g. "The active controller-manager process is the one that + wins its leader election" + - 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 + - `master` branch being renamed to `main` branch falls under this +- there are no strict guarantees about how and where control plane components + can and will run, e.g. + - they may run on machines that are not registered as Nodes for the Kubernetes + cluster they control + - they may run alongside user workloads on Nodes in the Kubernetes cluster + they control + - there may be one to many instances of each control plane component +- When using terminology that could be seen as generic, consider whether there + is enough context available to disambiguate potential meanings for the reader. +e.g. + - "instance" - an instance of what? + - "apiserver" - is this a generic apiserver? is this a kubernetes apiserver? + is this an apiserver that has been configured to be part of the kubernetes +control plane? + - "endpoint" - what's at the other end of this endpoint? + +## Context + +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: + - there is exactly one instance of each control plane component + - there is exactly one kubernetes node that hosts all of these components + - these components are guaranteed to run in a specific manner (systemd units, + 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 + members][sig-arch-thread] + +## Consequences + +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) +- known names/flags/fields/labels/annotations that may take time to change + - `"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) + - `--endpoint-reconciler-type master-count` + - 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 +[sig-arch-thread]: https://groups.google.com/u/1/g/kubernetes-sig-architecture/c/ZKUOPy2PNJ4/m/q3dC6pNtBQAJ +[framework]: https://git.k8s.io/community/wg-naming/language-evaluation-framework.md +[ietf-master]: https://tools.ietf.org/id/draft-knodel-terminology-00.html#master-slave +[drupal-master]: https://www.drupal.org/node/2275877 +[django-master]: https://github.com/django/django/pull/2692 +[system-privileged-group]: https://github.com/kubernetes/kubernetes/blob/a9d1482710a4c4baf112890882f4ab3d4be158a6/staging/src/k8s.io/apiserver/pkg/authentication/user/user.go#L71 diff --git a/sig-architecture/naming/recommendations/002-blacklist-whitelist-allowlist-denylist.md b/sig-architecture/naming/recommendations/002-blacklist-whitelist-allowlist-denylist.md new file mode 100644 index 00000000..e1bc8330 --- /dev/null +++ b/sig-architecture/naming/recommendations/002-blacklist-whitelist-allowlist-denylist.md @@ -0,0 +1,94 @@ +# Recommendation: replace blacklist/whitelist with allowlist/denylist + +**Last Updated**: 2020-12-01 + +**Status:** Accepted + +## Suggested Alternatives + +Replacements: +- `allowlist/denylist` + +## Context + +The underlying assumption of the whitelist/blacklist metaphor is that white = good and black = bad. Because colors in and of themselves have no predetermined meaning, any meaning we assign to them is cultural: for example, the color red in many Southeast Asian countries is lucky, and is often associated with events like marriages, whereas the color white carries the same connotations in many European countries. In the case of whitelist/blacklist, the terms originate in the publishing industry, which was historically dominated by America and England, two countries that participated in slavery and which grapple with their racist legacies to this day. + +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**: + +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** + + +**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] + +> 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** + +**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/) + +* [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) + +* [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=) + +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=` 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) +2. Open issues in all repositories for breaking changes, starting the deprecation cycle on old names. +3. Do documentation, test and non-"breaking" (external) changes next/concurrently with the above. +4. When ready, implement new names and await deprecation of old names identified in step 2. diff --git a/sig-architecture/naming/workflow.md b/sig-architecture/naming/workflow.md new file mode 100644 index 00000000..2ce4cc4c --- /dev/null +++ b/sig-architecture/naming/workflow.md @@ -0,0 +1,92 @@ +# Recommendations Workflow + +This document is a workflow for proposing language recommendations to +WG Naming. + +## Make a proposal + +Begin by sending a message outlining the proposed change to +the [WG Naming mailing list][mailing-list]. + +While WG Naming also discusses proposals in [#wg-naming][Slack], Slack is a lossy +communication forum which is much harder to review than the mailing list. + +Proposals should include information required to file a WG Naming +Architecture Decision Record (ADR): + +- The recommendation to be made +- Brief reasoning behind the change +- The context in which the existing term might be used +- Alternative recommendations +- A reasonable guess at the work required to make the change + +For more information about the WG Naming ADR, review the [template]. + +Following a mailing list proposal, contributors can continue discussion both on Slack +and at WG Naming meetings. + +### Filing a recommendation ADR + +If the working group's discussion determines that the recommendation is +reasonable and in line with our [framework] for language evaluation, +WG Naming leads formalize the recommendation with an ADR. + +For more information about the WG Naming ADR, review the [template]. + +An ADR must include: + +- Groups responsible for implementing the change +- The scope of the change in the Kubernetes project, as well as downstream + implications + +ADRs must be opened with a `/hold` to give an opportunity to seek approval +with the governance groups that with be responsible for implementation. + +After opening an ADR pull request, WG Naming leads +should: + +- Reply to any mailing list threads about the recommendation with a link to the + newly-opened PR, and CC any stakeholder groups +- Place the recommendation on the next meeting's agenda for review + +## Approval + +_This approval process is still under discussion, so here we will list out some +frequently-asked questions from our discussions thus far._ + +### What if a recommendation requires a KEP? + +ADRs should remain on hold until scoped area agrees with the direction. + +### What do we do when stakeholders disagree with a recommendation? + +Again, do not merge a recommendation until code owners from the scoped area +agree to it. + +### General guidance + +- SIG Architecture records decisions to "...not make the mistakes we made in + the past" +- Don’t block recording a recommendation on a plan to remediate all existing + uses; once the direction is agreed on by the code/content owners from the + scoped area, a recorded recommendation has value in guiding new/future work + +### Requirements + +- ADR is on hold until approved by scoped areas (e.g., SIG Architecture, SIG + Docs) +- Steering is tagged on the ADR for approval +- WG Naming lead establishes a Steering review/approval period with a lazy + consensus deadline of 3-5 business days +- WG Naming lead releases the hold and merges ADR + +## Implementation + +- WG Naming leads record accepted recommendation in a canonical location (TBD) + (for example, a style guide) +- Areas in scope are now responsible for implementation + +[framework]: language-evaluation-framework.md +[mailing-list]: https://groups.google.com/forum/#!forum/kubernetes-wg-naming +[slack]: https://kubernetes.slack.com/messages/wg-naming +[template]: ./recommendations/template.md diff --git a/wg-naming/OWNERS b/wg-naming/OWNERS deleted file mode 100644 index b85dde17..00000000 --- a/wg-naming/OWNERS +++ /dev/null @@ -1,8 +0,0 @@ -# See the OWNERS docs at https://go.k8s.io/owners - -reviewers: - - wg-naming-leads -approvers: - - wg-naming-leads -labels: - - wg/naming diff --git a/wg-naming/README.md b/wg-naming/README.md deleted file mode 100644 index 785b0d2b..00000000 --- a/wg-naming/README.md +++ /dev/null @@ -1,87 +0,0 @@ - -# Naming Working Group - - -## Stakeholder SIGs -* SIG Architecture -* SIG Contributor Experience -* SIG Docs - -## Meetings -* Regular WG Meeting: [Mondays at 10:30 PT (Pacific Time)](https://zoom.us/j/91522666403?pwd=WnRSNlNhNXhDWkR2ZU9ydGpsNWxtZz09) (monthly - second Monday of month). [Convert to your timezone](http://www.thetimezoneconverter.com/?t=10:30&tz=PT%20%28Pacific%20Time%29). - * [Meeting notes and Agenda](https://bit.ly/k8s-wg-naming-agenda). - * [Meeting recordings](https://www.youtube.com/playlist?list=PL69nYSiGNLP3BrAtDHyr8KTUfhBhCG7CD). - -## Organizers - -* Celeste Horgan (**[@celestehorgan](https://github.com/celestehorgan)**), CNCF -* Jaice Singer DuMars (**[@jdumars](https://github.com/jdumars)**), Apple -* Stephen Augustus (**[@justaugustus](https://github.com/justaugustus)**), Cisco - -## Emeritus Organizers - -* Zach Corleissen (**[@zacharysarah](https://github.com/zacharysarah)**) - -## Contact -- Slack: [#wg-naming](https://kubernetes.slack.com/messages/wg-naming) -- [Mailing list](https://groups.google.com/forum/#!forum/kubernetes-wg-naming) -- [Open Community Issues/PRs](https://github.com/kubernetes/community/labels/wg%2Fnaming) -- Steering Committee Liaison: Bob Killen (**[@mrbobbytables](https://github.com/mrbobbytables)**) - - -**The following section will be reworked and formalized as a charter once the -Working Group has been approved by the Steering Committee.** - -## Goals - -- Evaluate language and naming choices within the Kubernetes project, with - a specific initial focus of: - - Removing barriers to contribution and adoption by replacing harmful language with neutral terms whenever possible, including but not limited to language linked to racism, sexism, homophobia, transphobia, ableism, or discrimination against any protected or historically underrepresented group. - - Improving clarity of codebases and documentation by replacing idioms, - metaphors and slang specific to the English language -- Create a list of harmful terms with proposed replacements -- Define how any member of the Kubernetes project can - recommend language, how others can evaluate that proposal, and how to - implement replacements across all codebases. - - Provide an easily findable location for language recommendations and - follow-up issues, similar to an architectural decision record - - Define long-term ownership of this process -- Work with stakeholder SIGs to implement the changes recommended. We - anticipate the following: - - Provide stakeholder SIGs with guidance on naming, language conventions, and - processes - - Collaborate with SIG Architecture and other stakeholders on an - implementation timeline and strategies for dealing with follow-up issues - from renaming, like deprecations - - Collaborate with SIG Docs and SIG Contributor Experience on documenting - language recommendations and processes - - Work with the Code of Conduct Committee to add code architecture to the COC - -## Dissolution Criteria - -Once the Kubernetes community has: - -- A process in place to evaluate language changes on an ongoing basis -- A binding list of terms to avoid in codebases across the project -- A timeline on which to replace component names in the kubernetes/kubernetes - codebase -- Defined long-term ownership of the policies and processes this WG creates - -this WG will dissolve. - -## Post-formation Discussion Points - -- Discuss appropriate process for branch renaming with GitHub Administration - subproject (SIG ContribEx) -- Work with the Code of Conduct Committee to add code architecture to the COC -- A timeline on which to replace component names in the kubernetes/kubernetes -- Clarify that WG should not dissolve until after changes have been made - - diff --git a/wg-naming/governance.md b/wg-naming/governance.md deleted file mode 100644 index 5f15a42f..00000000 --- a/wg-naming/governance.md +++ /dev/null @@ -1,85 +0,0 @@ -# WG Naming governance - -## Uphold project values - -WG Naming upholds the Kubernetes project's [core values](/values.md). - -### Inclusive is better than exclusive - -> Broadly successful and useful technology requires different perspectives and skill sets which can only be heard in a welcoming and respectful environment. - -This document covers some specific ways in which WG Naming offers respect and welcome. - -> Our community shows respect for the time and effort put into a discussion regardless of where a contributor is on their growth path. - -Like other SIGs and working groups, WG Naming has prerequisite skills, training, and experience that are necessary for meaningful contribution. For example: - - - Education or professional experience in dismantling systemic discrimination - - Demonstrable familiarity with current antidiscrimination resources - - A track record of supporting inclusion in the Kubernetes project - -WG Naming has many stakeholders, with many people eager to add their voices. WG Naming invites folks who are new to antiracism or inclusive language, and folks less experienced with frameworks of discrimination to participate by observing and learning. WG Naming invites contributors who meet prerequisites to contribute within the scope of WG Naming’s goals. - -### Resources for antidiscrimination - -- https://developers.google.com/style/inclusive-documentation -- https://www.antiracismresources.info/#online-resources -- _How to Be An Antiracist_, Ibrahim X. Kendi -- _So You Want to Talk About Race_, Ijeoma Oluo - -### Scope of discussion - -WG Naming actively moderates discussion for speech that affirms the humanity of underrepresented minorities and affirms their ongoing experience of discrimination. For example: specific suggestions for replacement terms are welcome. Disagreement over the presence and impact of racism is not welcome. - -## Follow the community code of conduct - -Like all WGs and SIGs, WG Naming expects contributors to follow the [Kubernetes Code of Conduct (CoC)]. - -We raise this section’s topics as potential blockers to the work of WG Naming, since experience has shown they are a common and detrimental response. - -From the CoC: - -> Examples of unacceptable behavior by participants include: -> -> - Personal attacks -> - Trolling or insulting/derogatory comments - -**Note:** the CoC governs conduct, not intent. WG Naming leads may refer unacceptable conduct to the Code of Conduct Committee regardless of professed intent. - -[Kubernetes Code of Conduct (CoC)]: /code-of-conduct.md - -### Personal attacks - -Personal attacks include denying or questioning the lived experience of underrepresented minorities. For example: arguing that problematic terms "aren't racist", or any statements reducible or equivalent to "all lives matter". - -### Trolling - -Trolling includes: - -- [Concern trolling](https://en.wiktionary.org/wiki/concern_troll) - -- Derailing behavior - - Behavior that distracts from WG Naming's purpose or attempts to redirect participants' energy into minutiae or unrelated topics or goals. - - For example: - - insisting that previous decisions be re-argued - - insisting that WG Naming can take no action until all possible inequities are addressed - -- [Sea lioning](https://www.forbes.com/sites/marshallshepherd/2019/03/07/sealioning-is-a-common-trolling-tactic-on-social-media-what-is-it/) - - Endless demands for evidence; refusing to accept or acknowledge peer-reviewed scientific research; insisting that one's ignorance, whether real or feigned, be satisfied by the WG group to an individual's satisfaction. - - See the original Wondermark comic: [sea lions](http://wondermark.com/1k62/) - -- [Brigading](https://en.wikipedia.org/wiki/Vote_brigading) - - Attempting to overrepresent a viewpoint through participation bias - -## Deviations from [sig-governance] - -WG Naming leads may close or end meetings at their discretion to shut down trolling or protect the safety of community members. - -WG Naming [restricts the scope of discussion](#scope-of-discussion). - -[sig-governance]: /committee-steering/governance/sig-governance.md diff --git a/wg-naming/language-evaluation-framework.md b/wg-naming/language-evaluation-framework.md deleted file mode 100644 index 959e9270..00000000 --- a/wg-naming/language-evaluation-framework.md +++ /dev/null @@ -1,118 +0,0 @@ - -# A framework for evaluating harmful language - -## About - -The language evaluation framework is a guidance document developed by the Kubernetes Naming Working Group. It outlines a structured framework for evaluating language and terminology for harm to the community. This enables the community to navigate divisive conversations with a measure of clarity. - -The framework was created for an open source technology project. The framework may be applicable to other fields as well. - -## Using the framework - -The framework is divided into three sections: first-, second-, and third-order concerns, ranked in order of potential harm to the community. - -First-order concerns are language where harm is egregious, overt, and clearly problematic. Second-order concerns are language which is problematic but with a less definite impact. Third-order concerns indicate language that could use improvement but does no demonstrable harm. - -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. - -If a significant number of second- or third- order concerns are a “yes”, strongly consider replacing the language. - -This framework is intentionally non-prescriptive. The intention in this work is to reduce harm for the community; let harm reduction guide your decisions. - -### First-order concerns - -First-order concerns are characterized by: - -- Overtness: regardless of its use in the context of code or technology, there is little to no ambiguity outside of technology as to whether the language in question indicates harm -- Identity-specificity: language in question specifically unambiguously identifies a group of people - -#### Is the term overtly racist? - -Examples include “master/slave”. - -#### Is the term overtly sexist, transphobic, or pejorative about a gender identity? - -Examples do _not_ include “transclusion” of dependencies, or “binary” operators. - -#### Is the term overtly ableist, or pejorative to neurodiverse or disabled people - -Examples include performing “sanity checks”. - -#### Is the term overtly homophobic? - -Examples do not include “homogenizing” or “homogenous” data. - -### Second-order concerns - -Second-order concerns are characterized by: - -- Ambiguity: outside the context of code or technology, language might have connotations related to harmful scenarios like war, militarization, or policing, but the actual etymology of the term is not related to harm of a specific identity -- Lack of specific identity: concerns in this category do not target specific identities, or do so in a non-overt way - -#### Is the term violent? - -Examples include “KILL” commands in Unix systems. - -#### Is the term militaristic? - -Examples include “marshal/unmarshal”. - - -### Third-order concerns - -Third-order concerns are characterized by: - -- Clarity: is the language in use a metaphor that could be described more precisely using different words? - -- Anthropomorphism: does language unnecessarily humanize components or processes? - -- Idiomatic: Is language unclear to someone outside a specific culture? - - -#### Is the term evocative instead of descriptive? - -Examples include “PetSet” (evocative) versus “StatefulSet” (descriptive). - -#### Is the term ambiguous? - -Examples include the use of ABORT/STOP/KILL in Unix-like systems, where they map to specific behaviors, versus general usage in programming languages, where they map to different behaviors or are used interchangeably. - -## Footnotes - -### Changes over time - -In general, strong democratic societies become more progressive and accepting as time passes. This is a feature, not a bug. - -As a result, terms that were once deemed acceptable may, at some future point, be deemed unacceptable. - -We recommend: - -- Placing a date at the top of any documents/recommendations related to naming, language inclusivity, or harm reduction -- 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. - -In Kubernetes we mostly encounter [sea lions](http://wondermark.com/1k62/) (concern trolls), who seek to legitimize debate over false concerns in order to use up contributors' energy and time. - -We work with our GitHub and other moderation teams to shut down trolling behavior at the source and remove trolling content. - -In cases where it’s unclear whether the poster is a legitimate user or a troll, we direct the work back to them: because they’re clearly “legitimately interested” in this topic, we ask them to join us in the WG Naming mailing list, drafting a formal suggestion (attached to an email address and identity we can track) and suggesting replacement terminology. Most trolls do not want to put in the effort. - -Rather than be discouraged by trolls, consider it a heartening sign that you are engaged in meaningful work. - -### Kudos - -This work would not have come into shape without referencing the following resources freely available online. We thank the authors of these original documents for helping guide our thoughts on the topic: - -- [APA Style Guide: General Principles for reducing bias](https://apastyle.apa.org/style-grammar-guidelines/bias-free-language/general-principles) -- [Shopify Polaris Content Guidelines: Descriptive vs. Evocative names](https://polaris.shopify.com/content/naming#section-descriptive-vs-evocative-names) -- [CNET: Twitter engineers: out with the old words...](https://www.cnet.com/news/twitter-engineers-replace-racially-loaded-tech-terms-like-master-slave/) diff --git a/wg-naming/recommendations/000-template.md b/wg-naming/recommendations/000-template.md deleted file mode 100644 index 9779d80c..00000000 --- a/wg-naming/recommendations/000-template.md +++ /dev/null @@ -1,26 +0,0 @@ -# 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. - - -- 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 - -## Context - -- Provide information about the recommendation. Why does this proposal matter? Who does it affect? How will it help? How does it evaluate against the [language-evaluation-framework]? - -## Precedents - -Provide any research, links to PR(s) from the Kubernetes project or other communities, standards body documents, or style guides that provide precedent for this decision. - -## Impact - -Link to the results of a [Hound](https://cs.k8s.io/) keyword search. What impact will this change create? diff --git a/wg-naming/recommendations/001-master-control-plane.md b/wg-naming/recommendations/001-master-control-plane.md deleted file mode 100644 index 038ca252..00000000 --- a/wg-naming/recommendations/001-master-control-plane.md +++ /dev/null @@ -1,119 +0,0 @@ -# Recommendation: master -> control plane - -**Last Updated**: 2020-10-16 - -**Status**: Accepted - -## Recommendation - -Within the Kubernetes codebase, the term “master” is often used in reference to -[the kubernetes control plane][architecture], either as a whole or to some -subset of the components within. We recommend **control plane** to refer to the -set of components as a whole. We recommend **context-specific alternatives** -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 - control a kubernetes cluster" -- If it matters which specific component(s) or component instance is being - communicated with, be specific: - - endpoint, e.g. "we don't care whether a load balancer, apiserver, or other - component is behind this endpoint; we will talk only to this endpoint and no -other" - - instance, e.g. "we are going to create multiple control plane apiserver - instances; we will talk only to this specific instance" - - , 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 - - 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. - - 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: - - active/passive, e.g. "The active controller-manager process is the one that - wins its leader election" - - 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 - - `master` branch being renamed to `main` branch falls under this -- there are no strict guarantees about how and where control plane components - can and will run, e.g. - - they may run on machines that are not registered as Nodes for the Kubernetes - cluster they control - - they may run alongside user workloads on Nodes in the Kubernetes cluster - they control - - there may be one to many instances of each control plane component -- When using terminology that could be seen as generic, consider whether there - is enough context available to disambiguate potential meanings for the reader. -e.g. - - "instance" - an instance of what? - - "apiserver" - is this a generic apiserver? is this a kubernetes apiserver? - is this an apiserver that has been configured to be part of the kubernetes -control plane? - - "endpoint" - what's at the other end of this endpoint? - -## Context - -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: - - there is exactly one instance of each control plane component - - there is exactly one kubernetes node that hosts all of these components - - these components are guaranteed to run in a specific manner (systemd units, - 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 - members][sig-arch-thread] - -## Consequences - -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) -- known names/flags/fields/labels/annotations that may take time to change - - `"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) - - `--endpoint-reconciler-type master-count` - - 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 -[sig-arch-thread]: https://groups.google.com/u/1/g/kubernetes-sig-architecture/c/ZKUOPy2PNJ4/m/q3dC6pNtBQAJ -[framework]: https://git.k8s.io/community/wg-naming/language-evaluation-framework.md -[ietf-master]: https://tools.ietf.org/id/draft-knodel-terminology-00.html#master-slave -[drupal-master]: https://www.drupal.org/node/2275877 -[django-master]: https://github.com/django/django/pull/2692 -[system-privileged-group]: https://github.com/kubernetes/kubernetes/blob/a9d1482710a4c4baf112890882f4ab3d4be158a6/staging/src/k8s.io/apiserver/pkg/authentication/user/user.go#L71 diff --git a/wg-naming/recommendations/002-blacklist-whitelist-allowlist-denylist.md b/wg-naming/recommendations/002-blacklist-whitelist-allowlist-denylist.md deleted file mode 100644 index e1bc8330..00000000 --- a/wg-naming/recommendations/002-blacklist-whitelist-allowlist-denylist.md +++ /dev/null @@ -1,94 +0,0 @@ -# Recommendation: replace blacklist/whitelist with allowlist/denylist - -**Last Updated**: 2020-12-01 - -**Status:** Accepted - -## Suggested Alternatives - -Replacements: -- `allowlist/denylist` - -## Context - -The underlying assumption of the whitelist/blacklist metaphor is that white = good and black = bad. Because colors in and of themselves have no predetermined meaning, any meaning we assign to them is cultural: for example, the color red in many Southeast Asian countries is lucky, and is often associated with events like marriages, whereas the color white carries the same connotations in many European countries. In the case of whitelist/blacklist, the terms originate in the publishing industry, which was historically dominated by America and England, two countries that participated in slavery and which grapple with their racist legacies to this day. - -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**: - -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** - - -**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] - -> 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** - -**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/) - -* [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) - -* [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=) - -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=` 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) -2. Open issues in all repositories for breaking changes, starting the deprecation cycle on old names. -3. Do documentation, test and non-"breaking" (external) changes next/concurrently with the above. -4. When ready, implement new names and await deprecation of old names identified in step 2. diff --git a/wg-naming/workflow.md b/wg-naming/workflow.md deleted file mode 100644 index 2ce4cc4c..00000000 --- a/wg-naming/workflow.md +++ /dev/null @@ -1,92 +0,0 @@ -# Recommendations Workflow - -This document is a workflow for proposing language recommendations to -WG Naming. - -## Make a proposal - -Begin by sending a message outlining the proposed change to -the [WG Naming mailing list][mailing-list]. - -While WG Naming also discusses proposals in [#wg-naming][Slack], Slack is a lossy -communication forum which is much harder to review than the mailing list. - -Proposals should include information required to file a WG Naming -Architecture Decision Record (ADR): - -- The recommendation to be made -- Brief reasoning behind the change -- The context in which the existing term might be used -- Alternative recommendations -- A reasonable guess at the work required to make the change - -For more information about the WG Naming ADR, review the [template]. - -Following a mailing list proposal, contributors can continue discussion both on Slack -and at WG Naming meetings. - -### Filing a recommendation ADR - -If the working group's discussion determines that the recommendation is -reasonable and in line with our [framework] for language evaluation, -WG Naming leads formalize the recommendation with an ADR. - -For more information about the WG Naming ADR, review the [template]. - -An ADR must include: - -- Groups responsible for implementing the change -- The scope of the change in the Kubernetes project, as well as downstream - implications - -ADRs must be opened with a `/hold` to give an opportunity to seek approval -with the governance groups that with be responsible for implementation. - -After opening an ADR pull request, WG Naming leads -should: - -- Reply to any mailing list threads about the recommendation with a link to the - newly-opened PR, and CC any stakeholder groups -- Place the recommendation on the next meeting's agenda for review - -## Approval - -_This approval process is still under discussion, so here we will list out some -frequently-asked questions from our discussions thus far._ - -### What if a recommendation requires a KEP? - -ADRs should remain on hold until scoped area agrees with the direction. - -### What do we do when stakeholders disagree with a recommendation? - -Again, do not merge a recommendation until code owners from the scoped area -agree to it. - -### General guidance - -- SIG Architecture records decisions to "...not make the mistakes we made in - the past" -- Don’t block recording a recommendation on a plan to remediate all existing - uses; once the direction is agreed on by the code/content owners from the - scoped area, a recorded recommendation has value in guiding new/future work - -### Requirements - -- ADR is on hold until approved by scoped areas (e.g., SIG Architecture, SIG - Docs) -- Steering is tagged on the ADR for approval -- WG Naming lead establishes a Steering review/approval period with a lazy - consensus deadline of 3-5 business days -- WG Naming lead releases the hold and merges ADR - -## Implementation - -- WG Naming leads record accepted recommendation in a canonical location (TBD) - (for example, a style guide) -- Areas in scope are now responsible for implementation - -[framework]: language-evaluation-framework.md -[mailing-list]: https://groups.google.com/forum/#!forum/kubernetes-wg-naming -[slack]: https://kubernetes.slack.com/messages/wg-naming -[template]: ./recommendations/template.md -- cgit v1.2.3 From 941bc0a22bab1ceec4dc1ddb4be6cb8d0605f93d Mon Sep 17 00:00:00 2001 From: Stephen Augustus Date: Mon, 9 Aug 2021 14:18:30 -0400 Subject: generated: Remove WG Naming from sigs.yaml Signed-off-by: Stephen Augustus --- OWNERS_ALIASES | 4 ---- liaisons.md | 1 - sig-list.md | 1 - sigs.yaml | 36 ------------------------------------ 4 files changed, 42 deletions(-) diff --git a/OWNERS_ALIASES b/OWNERS_ALIASES index 5e3bb38d..82010eef 100644 --- a/OWNERS_ALIASES +++ b/OWNERS_ALIASES @@ -120,10 +120,6 @@ aliases: wg-multitenancy-leads: - srampal - tashimi - wg-naming-leads: - - celestehorgan - - jdumars - - justaugustus wg-policy-leads: - JimBugwadia - rficcaglia diff --git a/liaisons.md b/liaisons.md index 9d60b4b8..a89ea215 100644 --- a/liaisons.md +++ b/liaisons.md @@ -53,7 +53,6 @@ of SIGs, WGs and UGs. | [WG Data Protection](wg-data-protection/README.md) | Paris Pittman (**[@parispittman](https://github.com/parispittman)**) | | [WG IoT Edge](wg-iot-edge/README.md) | Derek Carr (**[@derekwaynecarr](https://github.com/derekwaynecarr)**) | | [WG Multitenancy](wg-multitenancy/README.md) | Jordan Liggitt (**[@liggitt](https://github.com/liggitt)**) | -| [WG Naming](wg-naming/README.md) | Bob Killen (**[@mrbobbytables](https://github.com/mrbobbytables)**) | | [WG Policy](wg-policy/README.md) | Christoph Blecker (**[@cblecker](https://github.com/cblecker)**) | | [WG Structured Logging](wg-structured-logging/README.md) | Davanum Srinivas (**[@dims](https://github.com/dims)**) | | [UG Big Data](ug-big-data/README.md) | Derek Carr (**[@derekwaynecarr](https://github.com/derekwaynecarr)**) | diff --git a/sig-list.md b/sig-list.md index fdc9b925..e9eb6f06 100644 --- a/sig-list.md +++ b/sig-list.md @@ -67,7 +67,6 @@ When the need arises, a [new SIG can be created](sig-wg-lifecycle.md) |[Data Protection](wg-data-protection/README.md)|* Apps
* Storage
|* [Xing Yang](https://github.com/xing-yang), VMware
* [Xiangqian Yu](https://github.com/yuxiangqian), Google
|* [Slack](https://kubernetes.slack.com/messages/wg-data-protection)
* [Mailing List](https://groups.google.com/forum/#!forum/kubernetes-data-protection)|* Regular WG Meeting: [Wednesdays at 9:00 PT (Pacific Time) (bi-weekly)](https://zoom.us/j/6933410772)
|[IoT Edge](wg-iot-edge/README.md)|* Multicluster
* Network
|* [Steve Wong](https://github.com/cantbewong), VMware
* [Cindy Xing](https://github.com/cindyxing), Microsoft
* [Dejan Bosanac](https://github.com/dejanb), Red Hat
|* [Slack](https://kubernetes.slack.com/messages/wg-iot-edge)
* [Mailing List](https://groups.google.com/forum/#!forum/kubernetes-wg-iot-edge)|* APAC WG Meeting: [Wednesdays at 5:00 UTC (every four weeks)](https://zoom.us/j/91251176046?pwd=cmdqclovM3R3eDB1VlpuL1ZGU1hnZz09)
* Regular WG Meeting (Pacific Time): [Wednesdays at 09:00 PT (every four weeks)](https://zoom.us/j/92778512626?pwd=MXhlemwvYnhkQmkxeXllQ0Z5VGs4Zz09)
|[Multitenancy](wg-multitenancy/README.md)|* API Machinery
* Auth
* Network
* Node
* Scheduling
* Storage
|* [Sanjeev Rampal](https://github.com/srampal), Cisco
* [Tasha Drew](https://github.com/tashimi), VMware
|* [Slack](https://kubernetes.slack.com/messages/wg-multitenancy)
* [Mailing List](https://groups.google.com/forum/#!forum/kubernetes-wg-multitenancy)|* Regular WG Meeting: [Tuesdays at 11:00 PT (Pacific Time) (biweekly)](https://zoom.us/my/k8s.sig.auth)
-|[Naming](wg-naming/README.md)|* Architecture
* Contributor Experience
* Docs
|* [Celeste Horgan](https://github.com/celestehorgan), CNCF
* [Jaice Singer DuMars](https://github.com/jdumars), Apple
* [Stephen Augustus](https://github.com/justaugustus), Cisco
|* [Slack](https://kubernetes.slack.com/messages/wg-naming)
* [Mailing List](https://groups.google.com/forum/#!forum/kubernetes-wg-naming)|* Regular WG Meeting: [Mondays at 10:30 PT (Pacific Time) (monthly - second Monday of month)](https://zoom.us/j/91522666403?pwd=WnRSNlNhNXhDWkR2ZU9ydGpsNWxtZz09)
|[Policy](wg-policy/README.md)|* Architecture
* Auth
* Multicluster
* Network
* Node
* Scheduling
* Storage
|* [Jim Bugwadia](https://github.com/JimBugwadia), Kyverno/Nirmata
* [Robert Ficcaglia](https://github.com/rficcaglia), SunStone
|* [Slack](https://kubernetes.slack.com/messages/wg-policy)
* [Mailing List](https://groups.google.com/forum/#!forum/kubernetes-wg-policy)|* Regular WG Meeting: [Wednesdays at 8:00 PT (Pacific Time) (semimonthly)](https://zoom.us/j/7375677271)
|[Reliability](wg-reliability/README.md)|* Architecture
* Cluster Lifecycle
* Release
* Scalability
* Testing
|* [David Eads](https://github.com/deads2k), Red Hat
* [Steve Kuznetsov](https://github.com/stevekuznetsov), Red Hat
* [Wojciech Tyczynski](https://github.com/wojtek-t), Google
|* [Slack](https://kubernetes.slack.com/messages/wg-reliability)
* [Mailing List](https://groups.google.com/forum/#!forum/kubernetes-wg-reliability)|* Regular WG Meeting: [Mondays at 11:00 PT (Pacific Time) (biweekly)](https://zoom.us/j/97964505804?pwd=R3hzSnArQWJHYmdWUnpSUDh3aXhFUT09)
|[Structured Logging](wg-structured-logging/README.md)|* API Machinery
* Architecture
* Cloud Provider
* Instrumentation
* Network
* Node
* Scheduling
* Storage
|* [Marek Siarkowicz](https://github.com/serathius), Google
* [Shubheksha Jalan](https://github.com/shubheksha), Apple
|* [Slack](https://kubernetes.slack.com/messages/wg-structured-logging)
* [Mailing List](https://groups.google.com/forum/#!forum/kubernetes-wg-structured-logging)|* Regular Meeting: [Thursdays at 14:30 UTC (biweekly)](https://zoom.us/j/96716142646?pwd=VmgrN29sbmhDREp3R0NtZlpGSlZ4Zz09)
diff --git a/sigs.yaml b/sigs.yaml index efd75b1e..b2af4e8f 100644 --- a/sigs.yaml +++ b/sigs.yaml @@ -2928,42 +2928,6 @@ workinggroups: liaison: github: liggitt name: Jordan Liggitt -- dir: wg-naming - name: Naming - stakeholder_sigs: - - Architecture - - Contributor Experience - - Docs - label: naming - leadership: - chairs: - - github: celestehorgan - name: Celeste Horgan - company: CNCF - - github: jdumars - name: Jaice Singer DuMars - company: Apple - - github: justaugustus - name: Stephen Augustus - company: Cisco - emeritus_leads: - - github: zacharysarah - name: Zach Corleissen - meetings: - - description: Regular WG Meeting - day: Monday - time: "10:30" - tz: PT (Pacific Time) - frequency: monthly - second Monday of month - url: https://zoom.us/j/91522666403?pwd=WnRSNlNhNXhDWkR2ZU9ydGpsNWxtZz09 - archive_url: https://bit.ly/k8s-wg-naming-agenda - recordings_url: https://www.youtube.com/playlist?list=PL69nYSiGNLP3BrAtDHyr8KTUfhBhCG7CD - contact: - slack: wg-naming - mailing_list: https://groups.google.com/forum/#!forum/kubernetes-wg-naming - liaison: - github: mrbobbytables - name: Bob Killen - dir: wg-policy name: Policy mission_statement: > -- cgit v1.2.3 From 5ee9f8e5cb4f2e5fcdb69bc823c0936d8a6b37b0 Mon Sep 17 00:00:00 2001 From: Stephen Augustus Date: Wed, 22 Sep 2021 03:05:56 -0400 Subject: sig-architecture/naming: Fixup markdownlint warnings Signed-off-by: Stephen Augustus --- .../naming/language-evaluation-framework.md | 46 ++++++------- .../naming/recommendations/000-template.md | 16 +++-- .../recommendations/001-master-control-plane.md | 46 +++++++------ .../002-blacklist-whitelist-allowlist-denylist.md | 75 ++++++++++------------ 4 files changed, 94 insertions(+), 89 deletions(-) diff --git a/sig-architecture/naming/language-evaluation-framework.md b/sig-architecture/naming/language-evaluation-framework.md index 959e9270..99cc0f50 100644 --- a/sig-architecture/naming/language-evaluation-framework.md +++ b/sig-architecture/naming/language-evaluation-framework.md @@ -9,24 +9,23 @@ The framework was created for an open source technology project. The framework m ## Using the framework -The framework is divided into three sections: first-, second-, and third-order concerns, ranked in order of potential harm to the community. +The framework is divided into three sections: first-, second-, and third-order concerns, ranked in order of potential harm to the community. First-order concerns are language where harm is egregious, overt, and clearly problematic. Second-order concerns are language which is problematic but with a less definite impact. Third-order concerns indicate language that could use improvement but does no demonstrable harm. 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. - -If a significant number of second- or third- order concerns are a “yes”, strongly consider replacing the language. +If a significant number of second- or third- order concerns are a “yes”, strongly consider replacing the language. This framework is intentionally non-prescriptive. The intention in this work is to reduce harm for the community; let harm reduction guide your decisions. ### First-order concerns -First-order concerns are characterized by: +First-order concerns are characterized by: - Overtness: regardless of its use in the context of code or technology, there is little to no ambiguity outside of technology as to whether the language in question indicates harm - Identity-specificity: language in question specifically unambiguously identifies a group of people @@ -37,19 +36,19 @@ Examples include “master/slave”. #### Is the term overtly sexist, transphobic, or pejorative about a gender identity? -Examples do _not_ include “transclusion” of dependencies, or “binary” operators. +Examples do _not_ include “transclusion” of dependencies, or “binary” operators. #### Is the term overtly ableist, or pejorative to neurodiverse or disabled people -Examples include performing “sanity checks”. +Examples include performing “sanity checks”. -#### Is the term overtly homophobic? +#### Is the term overtly homophobic? -Examples do not include “homogenizing” or “homogenous” data. +Examples do not include “homogenizing” or “homogenous” data. ### Second-order concerns -Second-order concerns are characterized by: +Second-order concerns are characterized by: - Ambiguity: outside the context of code or technology, language might have connotations related to harmful scenarios like war, militarization, or policing, but the actual etymology of the term is not related to harm of a specific identity - Lack of specific identity: concerns in this category do not target specific identities, or do so in a non-overt way @@ -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,46 +71,44 @@ 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). +Examples include “PetSet” (evocative) versus “StatefulSet” (descriptive). #### Is the term ambiguous? -Examples include the use of ABORT/STOP/KILL in Unix-like systems, where they map to specific behaviors, versus general usage in programming languages, where they map to different behaviors or are used interchangeably. +Examples include the use of ABORT/STOP/KILL in Unix-like systems, where they map to specific behaviors, versus general usage in programming languages, where they map to different behaviors or are used interchangeably. -## Footnotes +## Footnotes ### Changes over time -In general, strong democratic societies become more progressive and accepting as time passes. This is a feature, not a bug. +In general, strong democratic societies become more progressive and accepting as time passes. This is a feature, not a bug. -As a result, terms that were once deemed acceptable may, at some future point, be deemed unacceptable. +As a result, terms that were once deemed acceptable may, at some future point, be deemed unacceptable. We recommend: -- Placing a date at the top of any documents/recommendations related to naming, language inclusivity, or harm reduction +- Placing a date at the top of any documents/recommendations related to naming, language inclusivity, or harm reduction - 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. +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 Kubernetes we mostly encounter [sea lions](http://wondermark.com/1k62/) (concern trolls), who seek to legitimize debate over false concerns in order to use up contributors' energy and time. -We work with our GitHub and other moderation teams to shut down trolling behavior at the source and remove trolling content. +We work with our GitHub and other moderation teams to shut down trolling behavior at the source and remove trolling content. In cases where it’s unclear whether the poster is a legitimate user or a troll, we direct the work back to them: because they’re clearly “legitimately interested” in this topic, we ask them to join us in the WG Naming mailing list, drafting a formal suggestion (attached to an email address and identity we can track) and suggesting replacement terminology. Most trolls do not want to put in the effort. -Rather than be discouraged by trolls, consider it a heartening sign that you are engaged in meaningful work. +Rather than be discouraged by trolls, consider it a heartening sign that you are engaged in meaningful work. ### Kudos This work would not have come into shape without referencing the following resources freely available online. We thank the authors of these original documents for helping guide our thoughts on the topic: -- [APA Style Guide: General Principles for reducing bias](https://apastyle.apa.org/style-grammar-guidelines/bias-free-language/general-principles) +- [APA Style Guide: General Principles for reducing bias](https://apastyle.apa.org/style-grammar-guidelines/bias-free-language/general-principles) - [Shopify Polaris Content Guidelines: Descriptive vs. Evocative names](https://polaris.shopify.com/content/naming#section-descriptive-vs-evocative-names) -- [CNET: Twitter engineers: out with the old words...](https://www.cnet.com/news/twitter-engineers-replace-racially-loaded-tech-terms-like-master-slave/) +- [CNET: Twitter engineers: out with the old words...](https://www.cnet.com/news/twitter-engineers-replace-racially-loaded-tech-terms-like-master-slave/) diff --git a/sig-architecture/naming/recommendations/000-template.md b/sig-architecture/naming/recommendations/000-template.md index 9779d80c..6f666db3 100644 --- a/sig-architecture/naming/recommendations/000-template.md +++ b/sig-architecture/naming/recommendations/000-template.md @@ -1,26 +1,30 @@ # Recommendation: replace Old Term **Last Updated**: date PR was last updated, e.g. 2020-10-16 + **Status:** Accepted -## Suggested Alternatives +## Suggested Alternatives + +Replacements: -Replacements: - `new term`: description of where this term is applicable. - 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 - Provide information about the recommendation. Why does this proposal matter? Who does it affect? How will it help? How does it evaluate against the [language-evaluation-framework]? -## Precedents +## Precedents -Provide any research, links to PR(s) from the Kubernetes project or other communities, standards body documents, or style guides that provide precedent for this decision. +Provide any research, links to PR(s) from the Kubernetes project or other communities, standards body documents, or style guides that provide precedent for this decision. ## 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 diff --git a/sig-architecture/naming/recommendations/001-master-control-plane.md b/sig-architecture/naming/recommendations/001-master-control-plane.md index 038ca252..444d8aa2 100644 --- a/sig-architecture/naming/recommendations/001-master-control-plane.md +++ b/sig-architecture/naming/recommendations/001-master-control-plane.md @@ -1,6 +1,6 @@ # Recommendation: master -> control plane -**Last Updated**: 2020-10-16 +**Last Updated**: 2020-10-16 **Status**: Accepted @@ -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" - - , e.g. "we will simulate an etcd fault by running this + - , 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 diff --git a/sig-architecture/naming/recommendations/002-blacklist-whitelist-allowlist-denylist.md b/sig-architecture/naming/recommendations/002-blacklist-whitelist-allowlist-denylist.md index e1bc8330..59c5f356 100644 --- a/sig-architecture/naming/recommendations/002-blacklist-whitelist-allowlist-denylist.md +++ b/sig-architecture/naming/recommendations/002-blacklist-whitelist-allowlist-denylist.md @@ -4,9 +4,8 @@ **Status:** Accepted -## Suggested Alternatives +## Suggested Alternatives -Replacements: - `allowlist/denylist` ## Context @@ -15,80 +14,76 @@ 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** - -**Third-order concerns** +- Is the term violent? **Partially** +- Is the term militaristic? **No** -* 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 +## 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=` 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=` 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) -2. Open issues in all repositories for breaking changes, starting the deprecation cycle on old names. +2. Open issues in all repositories for breaking changes, starting the deprecation cycle on old names. 3. Do documentation, test and non-"breaking" (external) changes next/concurrently with the above. 4. When ready, implement new names and await deprecation of old names identified in step 2. -- cgit v1.2.3 From 7828c21011122ab7da59f7f55ca339411287be10 Mon Sep 17 00:00:00 2001 From: Stephen Augustus Date: Wed, 22 Sep 2021 03:33:46 -0400 Subject: sig-architecture: Update references to WG Naming Signed-off-by: Stephen Augustus --- sig-architecture/naming/workflow.md | 38 ++++++++++++++++++------------------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/sig-architecture/naming/workflow.md b/sig-architecture/naming/workflow.md index 2ce4cc4c..b2f30343 100644 --- a/sig-architecture/naming/workflow.md +++ b/sig-architecture/naming/workflow.md @@ -1,17 +1,17 @@ # Recommendations Workflow -This document is a workflow for proposing language recommendations to -WG Naming. +This document is a workflow for proposing language recommendations for the +Kubernetes project. ## Make a proposal Begin by sending a message outlining the proposed change to -the [WG Naming mailing list][mailing-list]. +the [SIG Architecture mailing list][mailing-list]. -While WG Naming also discusses proposals in [#wg-naming][Slack], Slack is a lossy -communication forum which is much harder to review than the mailing list. +While proposals can also be discussed in [Slack], it is a lossy communication +forum which is much harder to review than the mailing list. -Proposals should include information required to file a WG Naming +Proposals should include information required to file a Naming Architecture Decision Record (ADR): - The recommendation to be made @@ -20,29 +20,29 @@ Architecture Decision Record (ADR): - Alternative recommendations - A reasonable guess at the work required to make the change -For more information about the WG Naming ADR, review the [template]. +For more information about the Naming ADR, review the [template]. Following a mailing list proposal, contributors can continue discussion both on Slack -and at WG Naming meetings. +and at SIG Architecture meetings. ### Filing a recommendation ADR -If the working group's discussion determines that the recommendation is +If the SIG's discussion determines that the recommendation is reasonable and in line with our [framework] for language evaluation, -WG Naming leads formalize the recommendation with an ADR. +SIG Architecture leads will formalize the recommendation with an ADR. -For more information about the WG Naming ADR, review the [template]. +For more information about the Naming ADR, review the [template]. An ADR must include: -- Groups responsible for implementing the change +- The groups responsible for implementing the change - The scope of the change in the Kubernetes project, as well as downstream implications ADRs must be opened with a `/hold` to give an opportunity to seek approval with the governance groups that with be responsible for implementation. -After opening an ADR pull request, WG Naming leads +After opening an ADR pull request, SIG Architecture leads should: - Reply to any mailing list threads about the recommendation with a link to the @@ -76,17 +76,17 @@ agree to it. - ADR is on hold until approved by scoped areas (e.g., SIG Architecture, SIG Docs) - Steering is tagged on the ADR for approval -- WG Naming lead establishes a Steering review/approval period with a lazy +- SIG Architecture lead establishes a Steering review/approval period with a lazy consensus deadline of 3-5 business days -- WG Naming lead releases the hold and merges ADR +- SIG Architecture lead releases the hold and merges ADR ## Implementation -- WG Naming leads record accepted recommendation in a canonical location (TBD) +- SIG Architecture leads record accepted recommendation in a canonical location (TBD) (for example, a style guide) - Areas in scope are now responsible for implementation [framework]: language-evaluation-framework.md -[mailing-list]: https://groups.google.com/forum/#!forum/kubernetes-wg-naming -[slack]: https://kubernetes.slack.com/messages/wg-naming -[template]: ./recommendations/template.md +[mailing-list]: https://groups.google.com/forum/#!forum/kubernetes-sig-architecture +[slack]: https://kubernetes.slack.com/messages/sig-architecture +[template]: ./recommendations/000-template.md -- cgit v1.2.3