Skip to content

Commit 4467884

Browse files
pwittrockpwittrock
committed
First draft of a document outlining the api review process
1 parent b500dda commit 4467884

File tree

4 files changed

+288
-0
lines changed

4 files changed

+288
-0
lines changed

‎contributors/design-proposals/api-proposal-design-template.md

+84
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
# Description of your Api
2+
3+
## Owners
4+
5+
Sig owner: list of sigs that will own the design, implementation, and support
6+
Individual owners: list of individual GitHub users that will own the design, implementation, and support
7+
8+
## Abstract
9+
10+
4-8 sentence description of the problem and solution. Bullet points welcome.
11+
12+
## Motivation
13+
14+
4-8 sentence of the current state and why it is insufficient.
15+
16+
## Use cases
17+
18+
Bullet point list of use cases this proposal is meant to address.
19+
20+
- As a cluster administrator...
21+
- As a application developer...
22+
- As a Kubernetes extension developer...
23+
24+
## Dependencies and deadlines
25+
26+
List of features that will depend on these changes.
27+
28+
List of features that these changes will depend upon.
29+
30+
**Include any deadlines that are related.** e.g. another feature depends on this and it is slated for 1.x.
31+
32+
## Proposed changes for new types
33+
34+
Declare the proposed Group / Version / Kind for any new types created as part of this proposal.
35+
36+
Describe how the new types will be used by the end user. Include sample yaml config and full walkthrough examples of
37+
1 or more usecases.
38+
39+
### Defaulting
40+
41+
Describe defaulting that will be performed on the new types
42+
43+
### Validation
44+
45+
Describe validation of fields on new types
46+
47+
### Patching lists - strategic merge keys
48+
49+
For any list fields, describe whether they will be replaced when patched or merged. If merged,
50+
describe the merge key that will be used.
51+
52+
### Controllers
53+
54+
Describe any controllers that will be added or updated.
55+
56+
## Proposed changes to existing types
57+
58+
Declare any new fields for existing types and their version. Will the fields be added as first class fields or
59+
as annotations?
60+
61+
### Defaulting
62+
63+
Describe any defaulting for new fields
64+
65+
### Validation
66+
67+
Describe any validation for new fields
68+
69+
### Controllers
70+
71+
Describe changes to controllers for new fields
72+
73+
### Patching lists - strategic merge keys
74+
75+
For any list fields, describe whether they will be replaced when patched or merged. If merged,
76+
describe the merge key that will be used.
77+
78+
## Impact on backwards / forwards compatibility
79+
80+
Describe any impact on backwards / forwards compatibility
81+
82+
## Alternatives considered
83+
84+
List alternative solutions to the use cases.

‎contributors/design-proposals/api-proposal-issue-template.md

+19
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Description of your Api
2+
3+
## Abstract
4+
5+
4-8 sentence description of the problem and solution. Bullet points welcome.
6+
7+
## Motivation
8+
9+
4-8 sentence of the current state and why it is insufficient.
10+
11+
## Use cases
12+
13+
Bullet point list of use cases this proposal is meant to address
14+
15+
## Dependencies and deadlines
16+
17+
List of features that will depend on these changes.
18+
19+
List of features that these changes will depend upon.

‎contributors/devel/contributing-api-changes.md

+134
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
# Guidelines for contributing api changes
2+
3+
## Overview
4+
5+
Modifications to the core Kubernetes api have a material impact on the Kubernetes project, and
6+
undergo thorough review and discussion before they are accepted. This document outlines the
7+
review process and what is expected of api contributors.
8+
9+
## Changes that qualify as api changes
10+
11+
Any changes to existing or new apis are subject to the process outlined in this document.
12+
13+
The following qualify as api changes:
14+
15+
- Adding, removing, or modifying api types (e.g. through types.go, or by defining a new annotation)
16+
- Changing the version of an existing type (e.g. v1alpha1 to v1beta1)
17+
- Adding, removing, or modifying subresources for existing types. (e.g. /scale)
18+
- Material changes to how fields on existing types are interpreted / used
19+
20+
The following on their own do not qualify as api changes, but should follow the process defined by the related
21+
[special interest groups].
22+
23+
- Adding or changing a command or flag to kubectl: sig-cli
24+
- Building new command line tools: sig-cli
25+
- Adding or changing a flag to kubelet: sig-node
26+
- Adding or changing a flag to apiserver: sig-api-machinery
27+
- Refactoring code
28+
- Building extensions
29+
30+
## Life of an api change
31+
32+
1. Start a discussion
33+
2. Write a short description
34+
3. Write a detailed design proposal
35+
4. Schedule a design review
36+
5. Implement the proposal
37+
38+
### Start a discussion.
39+
40+
Expected time for decision: 1-4 weeks (depending on the sig and feature)
41+
42+
Start a discussion with the relevant [special interest groups] that will [own] the changes.
43+
Depending on the sig, this may be done via sig meetings, email groups, slack channel, etc.
44+
45+
### Write a short description
46+
47+
Expected time for decision: 2 weeks
48+
49+
Write a short description of the api changes by copying the [design summary template]
50+
into a new issue, and [@mention] @kubernetes/api-reviewers and the owning sig reviewers
51+
group.
52+
53+
Determine whether @kubernetes/api-reviewers is willing to accept a design proposal
54+
for your feature. The answer could be "no, we don't want to solve this problem this way."
55+
or "no, this is something we want, but cannot commit the resources to reviewing it this release."
56+
57+
### Write a detailed design proposal
58+
59+
Expected time for initial feedback: 3-6 weeks
60+
61+
Write a detailed design proposal PR using the [design proposal PR template]. [@mention]
62+
@kubernetes/api-reviewers and the appropriate sigs on the PR and reference the original
63+
issue in the PR description.
64+
65+
### Schedule a design review
66+
67+
Expected time for next slot: 4-8 weeks
68+
69+
Schedule a time slow for your design to be reviewed.
70+
71+
Design approvers:
72+
- @smarterclayton
73+
- @bgrant
74+
- @thockin
75+
76+
### Implement the proposal
77+
78+
Once the proposal has been accepted an merged, you can begin implementing the solution.
79+
80+
## How to escalate
81+
82+
Escalation should be done through the owning sig. If you need help getting attention, reach out to your
83+
sig.
84+
85+
## Api change considerations
86+
87+
First read the [api changes] document for background on how to make changes in the api.
88+
89+
When writing a design proposal, you must consider the following:
90+
91+
### Api version semantics
92+
93+
- *Alpha*
94+
95+
Alpha versioned apis DO NOT guarantee backward compatibility between Kubernetes minor versions.
96+
97+
- *Beta*
98+
99+
Beta versioned apis DO guarantee backward compatibility between Kubernetes minor versions but
100+
are may have some known issues or unaddressed edge cases. Beta apis may miss some functionality
101+
that would be needed to consider the api GA.
102+
103+
- GA
104+
105+
GA versioned apis DO guarantee backward compatibility between Kubernetes minor versions and
106+
are considered to be fully featured. GA apis should have few known issues or edge cases.
107+
108+
### Api group semantics
109+
110+
It is important to pick the correct api group for your api. This will ensure that it is discoverable
111+
by users and is maintained in concert with related apis. Current api groups:
112+
113+
| Group | Description |
114+
|---|---|
115+
| abac | |
116+
| apps | |
117+
| authentication | |
118+
| authorization | |
119+
| autoscaling | |
120+
| batch | |
121+
| certificates | |
122+
| componentconfig | |
123+
| imagepolicy | |
124+
| policy | |
125+
| rbac | |
126+
| settings | |
127+
| storage | |
128+
129+
[@mention]: https://help.github.com/articles/basic-writing-and-formatting-syntax/#mentioning-users-and-teams
130+
[own]: https://github.com/kubernetes/community/blob/master/contributors/sig-ownership.md
131+
[special interest groups]: https://github.com/kubernetes/community/blob/master/README.md#special-interest-groups-sig
132+
[design proposal PR template]: https://github.com/kubernetes/community/blob/master/contributors/design-proposals/api-proposal-design-template.md
133+
[design summary template]: https://github.com/kubernetes/community/blob/master/contributors/design-proposals/api-proposal-issue-template.md
134+
[api changes]: https://github.com/kubernetes/community/blob/master/contributors/devel/api_changes.md

‎contributors/sig-ownership.md

+51
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
# Sig Ownership Responsibilities
2+
3+
## Overview
4+
5+
This document describes the commitment that is undertaken by a [special interest group] as part of owning
6+
a feature or api change. This applies to changes made to the [kubernetes/kubernetes] repo.
7+
8+
## Design
9+
10+
Depending on the size and impact of a feature, the design may need to go through a review process. Changes
11+
that do not directly impact the api should follow the process defined by the owning sig. Changes that
12+
do impact the api must go through an [api review] process. Even non-api changes must think carefully about
13+
backwards compatibility to ensure clusters will continue to function correctly after an upgrade or downgrade.
14+
15+
## Implementation
16+
17+
Implementation includes writing and reviewing the code for the new feature.
18+
19+
## Release tracking
20+
21+
The owning special interest group must create an issue in [kubernetes/features] and respond to comments
22+
on the feature. The feature issue MUST be updated with the current status within 1-2 days after feature freeze.
23+
24+
## Testing
25+
26+
Testing must be complete before the implementation is merged.
27+
28+
### Unit + integration testing
29+
30+
All new features must have appropriate coverage with unit + integration tests.
31+
32+
### E2e testing
33+
34+
E2e tests for a feature are owned by the sig that owns the feature, and must consistently pass.
35+
Tests that periodically fail must be fixed within the flake SLA defined for the project.
36+
37+
### Upgrade testing
38+
39+
Changes that could be impacted by upgrade / downgrades of a cluster must have automated tests to verify
40+
functionality during and after upgrade / downgrades.
41+
42+
### Client-server version skew testing
43+
44+
Any changes that break compatibility with client-server version skew tests of +-1 minor release must be resolved.
45+
46+
## Documentation
47+
48+
[special interest group]: https://github.com/kubernetes/community/blob/master/README.md#special-interest-groups-sig
49+
[kubernetes/kubernetes]: https://github.com/kubernetes/kubernetes
50+
[kubernetes/features]: https://github.com/kubernetes/features/
51+
[api review]: https://github.com/kubernetes/community/blob/master/contributors/contributing-api-changes.md

0 commit comments

Comments
 (0)