Improve documentation about community norms and processes #350
Description
The incubator process is currently very light on details about a number of facets of the community. As an example, the role of the Champion is defined as:
Potential Champions come from the set of all Kubernetes approvers and reviewers with the hope that they will be able to teach the Incubator Project about Kubernetes community norms and processes. The Champion is the primary point of contact for the Incubator Project team; and will help guide the team through the process. The majority of the mentorship, review, and advice will come from the Champion. Being a Champion is a significant amount of work and active participation in the sponsored project is encouraged.
The 'community norms and processes' referred to are very sparsely defined.
Since we are attempting to control growth and sprawl in kubernetes/kubernetes, it is logical to assume that in the future many people will make their entrance into the development part of our community via the incubator process. We should ensure that newcomers have a way to understand the community norms and processes in a way that:
- Doesn't depend on the personal knowledge level of an incubator repo Champion
- Doesn't depend on the personal bandwidth of an incubator repo Champion
- Is accurate, high-fidelity, and maintained by the community
Our experience from SIG service catalog has been that:
- Newcomers to the community who make contact first with an incubator do not have an easy way to familiarize themselves with the community norms and processes
- Because the norms and processes knowledge exists across the minds of many different individuals and has been transmitted via oral history, few people fully know what the established norms and processes are
- Knowledge transmission via retelling and answering individual questions is extremely inefficient and time consuming
- Motivation and rationale behind norms are not always clear to people who are familiar with the norms and processes
I think it would improve things if we:
- Clearly define the most important norms and process that should be followed; there are probably different ones that become important at different levels of maturity
- Clearly define which norms and processes must be adopted as exit criteria to incubation
- Document each norm and process from the above clearly, with onboarding instructions for things that require setup (bots, CI, etc)
Specific norms and processes from our experience in SIG service catalog:
- Code review / approval process:
- Whose approval is needed for a particular change?
- Pointers to automation for reviews and approvals
- Overall approach to generated code:
- What code is generated?
- Which generated code is commited to source control?
- Dependency management and vendoring code:
- Which dependency management tool should be used?
- Are dependencies vendored?
- Overall system architecture patterns:
- What is the lifecycle of an API request?
- How does one construct an API server?
- How does one create a new controller?
- Testing
- What level of testing is expected/required?
- What dependencies can a repository require for testing? Viz: must an incubator repo be testable on a laptop without an internet connection? With an internet connection?
Though this issue has already mentioned the following, I want to note again for emphasis that in addition to the facts for these, it is also critical to document the rationale behind the facts.
Specific asks for this issue:
- Let's add some specificity about the areas I've cited that we had some trouble with in the service catalog SIG
- Note: it's totally possible that we won't wind up wanting to be prescriptive in certain areas -- we should be explicit about those too
- Let's try to have (1) done by the time 1.6 is released