1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
|
# Recommendations Workflow
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 [SIG Architecture mailing list][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 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 Naming ADR, review the [template].
Following a mailing list proposal, contributors can continue discussion both on Slack
and at SIG Architecture meetings.
### Filing a recommendation ADR
If the SIG's discussion determines that the recommendation is
reasonable and in line with our [framework] for language evaluation,
SIG Architecture leads will formalize the recommendation with an ADR.
For more information about the Naming ADR, review the [template].
An ADR must include:
- 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, SIG Architecture 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
- SIG Architecture lead establishes a Steering review/approval period with a lazy
consensus deadline of 3-5 business days
- SIG Architecture lead releases the hold and merges ADR
## Implementation
- 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-sig-architecture
[slack]: https://kubernetes.slack.com/messages/sig-architecture
[template]: ./recommendations/000-template.md
|
