Proposal: Recording our recommendations in k/community using ADR-like files

[Celeste Horgan]

Hi folks,

A few of our discussions have reached consensus (or something near it), we need to think about how we'd like to record our decisions for everyone in the Kubernetes community to see.

Here's what I propose:

1. Adapt Micheal Nygard's Architectural Descision Record format slightly to include the following major fields:

• [Title] (i.e, WG Naming Recommendation: Old term -> New Term)
• [Status] (Accepted on DD/MM/YYYY. [list, of, participants, in, discussion])
• [Recommendation] (Formalize recommendation in title, provide a brief, 1-3 sentence summary of reasoning behind it, if needed. Provide alternate recommendations as needed.)
• [Context/precedents] (If existing, provide any research, links to PR(s) from other communities, etc. that provide precedent for this decision.
  
• [Consequences/implementation path] Starting with a Hound keyword search, note any major changes that will result by making this change.

2. PR decisions, as we make them to a subdirectory in https://github.com/kubernetes/community/tree/master/wg-naming 

Thoughts?

Some open questions I have for the group:

1. At what point do we invite others (Steering, i.e.) for comment?

2. Who, outside this group and Steering, gets to have their voice heard when we open a PR?

Cheers,

Celeste

[Sue Kocher]

Notes from the sidelines...
1. There needs to be a representative in the body making these decisions who has linguistic knowledge. I say this from painful experience trying to work out these naming issues at my company. These substitute terms, whatever they are, need to be translatable and free from culture-bound metaphors. People who do not understand language or L10n cannot see or prepare for this...
2. Re: the fields suggested above. I see "Context/precedents" which needs to be specific, not just about wording decisions, but about exactly what those words apply to.  No one-size-fits-all will be found.
Decisions for substitute terms need to be determined by technology or other types of context. There will not be one set of terms that will fit all situations inside k8s, let alone in the wider world where offensive terminology is being discussed. Terms like replica, secondary, child, worker, copy, etc. etc. will make sense in some contexts and not others. This also is hard to explain to people who only know one language or who think only in terms of their own culture.

(I am a terminologist and global language specialist at SAS)

[Bailey Hayes]

From what I can tell, this will be the first time ADR's are used for kubernetes. If there's another example within the k8s community, it might be helpful to link as a reference.

The alternative to ADR's is to use KEPs to capture decisions. I realize this might not be the best fit since these are typically focused on design and features. I read through this section and I think it's reasonable to twist decisions to fit https://github.com/kubernetes/enhancements#is-my-thing-an-enhancement.

Pros of using KEPs:

• Existing infrastructure, e.g. kepctl, Hugo site that renders KEPs.
• Answers the questions around who/what/when/where to invite others for comment. KEPs were designed to facilitate this.
• ADR's are meant to be "locked-in" and then superseded when the decision is modified. KEPs are meant to grow overtime. This seems like a better fit for the list of terms. 

One thing I like about ADR's is that they are local to the repo. From what I understand, this is also acceptable with KEPs, in that they do not have to live in the kubernetes/enhancements repo.

[Celeste Horgan]

Hmm.

While some aspects of what we're doing are KEP-like (this will take multiple cycles to complete, requires effort), others are distinctly un-KEP like, specifically: we're making recommendations rather than proposing changes, because WGs can't own code changes (and therefore cannot drive a KEP).

Celeste