93 lines
3.2 KiB
Markdown
93 lines
3.2 KiB
Markdown
# 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
|