Skip to content

Commit 7e828ea

Browse files
pwittrockpwittrock
committed
First iteration outlining the api review process
Address PR comments
1 parent f841d02 commit 7e828ea

File tree

6 files changed

+435
-2
lines changed

6 files changed

+435
-2
lines changed

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

+143
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
# Description of your API
2+
3+
Initial API version: v1alpha1
4+
5+
## Owners
6+
7+
SIG owner: list of SIG that will own the design, implementation, and support
8+
Individual owners: list of individual GitHub users that will own the design, implementation, and support
9+
10+
## Abstract
11+
12+
4-8 sentence description of the problem and solution. Bullet points welcome.
13+
14+
## Motivation
15+
16+
4-8 sentence of the current state and why it is insufficient.
17+
18+
## Use cases
19+
20+
Bullet point list of use cases this proposal is meant to address.
21+
22+
- As a cluster administrator...
23+
- As a application developer...
24+
- As a Kubernetes extension developer...
25+
26+
## Requirements
27+
28+
Bullet point list of new API requirements. Requirements will in part be driven by use
29+
cases, but may have additional engineering or interoperability requirements:
30+
31+
- User requirement
32+
- Engineering requirement
33+
- Interoperability requirement
34+
35+
## Overview subsequent versions
36+
37+
Subsequent versions will require their own API proposals, however it is important to include
38+
the plans for them here to provide a broader picture.
39+
40+
### Beta
41+
42+
*Use cases*
43+
44+
- Use cases for transitioning to Beta
45+
46+
*Requirements*
47+
48+
- Additional requirements for transitioning to Beta
49+
50+
### GA
51+
52+
*Use cases*
53+
54+
- Use cases for transitioning to Beta
55+
56+
*Requirements*
57+
58+
- Additional requirements for transitioning to Beta
59+
60+
## Dependencies and deadlines
61+
62+
List of features that will depend on these changes.
63+
64+
List of features that these changes will depend upon.
65+
66+
**Include any deadlines that are related.** e.g. another feature depends on this and it is slated for 1.x.
67+
68+
## Proposed changes for new types or existing types
69+
70+
Declare the proposed Group / Version / Kind for any new types created as part of this proposal.
71+
72+
Declare any new fields for existing types and their version. Will the fields be added as first class fields or
73+
as annotations?
74+
75+
Describe how any new types or fields will be used by the end user. Include sample yaml config and full
76+
walkthrough examples of 1 or more usecases.
77+
78+
### Defaulting
79+
80+
Describe defaulting that will be done
81+
82+
### Validation
83+
84+
Describe validation the will be done
85+
86+
### Patching lists - strategic merge keys
87+
88+
For any list fields, describe whether they will be replaced when patched or merged. If merged,
89+
describe the merge key that will be used.
90+
91+
**mergeKeys must be unique and required for all elements in the list!** Consequences of using a
92+
non-unique or optional merge key may be severe.
93+
94+
### Controllers
95+
96+
Describe any controllers that will be added or updated.
97+
98+
### Subresources
99+
100+
Describe any subresources that will be added.
101+
102+
## Mandatory API pre-flight check list
103+
104+
The following items must be considered and explained when adding or changing and API.
105+
106+
### API convention deviations
107+
108+
List and justify any deviations from [API conventions]. *None* is acceptable if
109+
there are no deviations.
110+
111+
### Impact on backwards / forwards compatibility
112+
113+
Describe any impact on backwards / forwards [compatibility].
114+
115+
Known future incompatibility risks and mitigation.
116+
117+
### Security, PII and authz
118+
119+
Describe any security concerns or PII that is managed by the API. Describe
120+
any special considerations that must be made for authentication or
121+
authorization.
122+
123+
### Cli and client library considerations.
124+
125+
Describe any interactions with the cli or client libraries.
126+
127+
Is functionality in this API already present in the cli? If so, was is the interaction and
128+
path forward?
129+
130+
Is server side garbage collection needed / enabled?
131+
132+
## Alternatives considered
133+
134+
List alternative solutions to the use cases. Include an analysis of any of
135+
the following that apply.
136+
137+
- Client side solutions
138+
- Existing APIs or solutions that are similar
139+
- Existing workarounds - include solutions that compose existing APIs
140+
- Using ThirdPartyResources
141+
142+
[API conventions]: https://github.com/kubernetes/community/blob/master/contributors/devel/api-conventions.md
143+
[compatibility]: https://github.com/kubernetes/community/blob/master/contributors/devel/api_changes.md#on-compatibility

‎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/api_changes.md

+5-2
Original file line numberDiff line numberDiff line change
@@ -638,8 +638,11 @@ tips](../api.md#v1-conversion-tips))
638638
via a flag should not create new bugs in unrelated features; because the feature
639639
is new, it may have minor bugs
640640
- Support: the project commits to complete the feature, in some form, in a
641-
subsequent Stable version; typically this will happen within 3 months, but
642-
sometimes longer; releases should simultaneously support two consecutive
641+
subsequent Stable version; As a general guideline, beta features should remain in beta for
642+
2 releases after the feature has been introduced (GA development begins
643+
after the feature has been beta for 1 full release cycle).
644+
This provides time to gather user feedback before transitioning from beta to GA;
645+
releases should simultaneously support two consecutive
643646
versions (e.g. `v1beta1` and `v1beta2`; or `v1beta2` and `v1`) for at least one
644647
minor release cycle (typically 3 months) so that users have enough time to
645648
upgrade and migrate objects

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

+154
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
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+
## Process overview
10+
11+
*Proposal process*
12+
13+
All API changes require a formal proposal to be made, reviewed and accepted. The proposal will be
14+
considered accepted once the proposal PR has been merged.
15+
16+
*Feature process*
17+
18+
All API changes require an issue to be filed in the [kubernetes/features] repo. The
19+
issue will be used by release coordinators to track which features are slated for a
20+
release milestone.
21+
22+
## Changes that qualify as API changes
23+
24+
All changes to existing or new APIs are subject to the process outlined in this document.
25+
26+
The following qualify as API changes:
27+
28+
- Adding, removing, or modifying API types (e.g. through types.go, or by defining a new annotation)
29+
- Changing the version of an existing type (e.g. v1alpha1 to v1beta1)
30+
- Adding, removing, or modifying subresources for existing types. (e.g. /scale)
31+
- Material changes to how fields on existing types are interpreted / used - including, but not limited to
32+
validation and defaulting of the fields.
33+
34+
The following on their own do not qualify as API changes, but should follow the process defined by the related
35+
[special interest groups].
36+
37+
- Adding or changing a command or flag to kubectl: See [contributing to SIG cli]
38+
- Building new command line tools: See [contributing to SIG cli]
39+
- Adding or changing a flag to kubelet: sig-node
40+
- Adding or changing a flag to apiserver: sig-api-machinery
41+
- Refactoring code
42+
- Building extensions
43+
44+
## Life of an API change
45+
46+
1. Start a discussion
47+
2. Write a short description
48+
3. Write a detailed design proposal in the [kubernetes/community] repo
49+
4. Schedule a design review
50+
5. File an issue in the [kubernetes/features] repo that links to the proposal
51+
6. Implement the proposal in the [kubernetes/kubernetes] repo
52+
7. Write user facing documentation on [kubernetes/kubernetes.github.io]
53+
54+
### Start a discussion.
55+
56+
Expected time for decision: 1-4 weeks (depending on the SIG and feature)
57+
58+
Start a discussion with the relevant [special interest groups] that will [own] the changes.
59+
Depending on the SIG, this may be done via SIG meetings, email groups, slack channel, etc.
60+
61+
### Write a short description
62+
63+
Expected time for decision: 2 weeks
64+
65+
Write a short description of the API changes by copying the [design summary template]
66+
into a new issue, and [@mention] @kubernetes/api-reviewers and the owning SIG reviewers
67+
group.
68+
69+
Determine whether @kubernetes/api-reviewers is willing to accept a design proposal
70+
for your feature. The answer could be "no, we don't want to solve this problem this way."
71+
or "no, this is something we want, but cannot commit the resources to reviewing it this release."
72+
73+
### Write a detailed design proposal
74+
75+
Expected time for initial feedback: 3-6 weeks
76+
77+
Write a detailed design proposal PR using the [design proposal PR template]. [@mention]
78+
@kubernetes/api-reviewers and the appropriate SIGs on the PR and reference the original
79+
issue in the PR description.
80+
81+
### Schedule a design review
82+
83+
Expected time for next slot: 4-8 weeks
84+
85+
Schedule a time for your design to be reviewed.
86+
87+
See the current list of [design approvers](https://github.com/orgs/kubernetes/teams/api-approvers)
88+
89+
**Note**: these are the current reviewers, we are still figuring out how to
90+
add/remove people to this list. For more information, see the
91+
[governance discussion](https://groups.google.com/forum/#!topic/kubernetes-dev/4e8WOnMvZC0)
92+
93+
### Implement the proposal
94+
95+
Once the proposal has been accepted an merged, you can begin implementing the solution.
96+
97+
## How to escalate
98+
99+
Escalation should be done through the owning SIG. If you need help getting attention, reach out to your
100+
SIG.
101+
102+
## API change considerations
103+
104+
First read the [API changes] document for background on how to make changes in the API.
105+
106+
When writing a design proposal, you must consider the following:
107+
108+
### API versions
109+
110+
See [API versions] for details on the semantic meaning of the API versions. Changes to how
111+
existing fields are validated, defaulted, or interpreted requires an API version change.
112+
113+
### API groups
114+
115+
It is important to pick the correct API group for your API. This will ensure that it is discoverable
116+
by users and is maintained in concert with related APIs. Current API groups:
117+
118+
| Group | Description |
119+
| ------ | ----------- |
120+
| abac | |
121+
| apps | |
122+
| authentication | |
123+
| authorization | |
124+
| autoscaling | |
125+
| batch | |
126+
| certificates | |
127+
| imagepolicy | |
128+
| policy | |
129+
| rbac | |
130+
| settings | |
131+
| storage | |
132+
133+
134+
## Related documents
135+
136+
- [API changes]
137+
- [API conventions]
138+
- [OARP roles model](https://stumblingabout.com/tag/oarp/)
139+
- [RACI roles model](http://www.valuebasedmanagement.net/methods_raci.html)
140+
141+
[API versions]: https://github.com/kubernetes/community/blob/master/contributors/devel/api_changes.md#alpha-beta-and-stable-versions
142+
[@mention]: https://help.github.com/articles/basic-writing-and-formatting-syntax/#mentioning-users-and-teams
143+
[own]: https://github.com/kubernetes/community/blob/master/contributors/sig-ownership.md
144+
[special interest groups]: https://github.com/kubernetes/community/blob/master/README.md#special-interest-groups-sig
145+
[design proposal PR template]: https://github.com/kubernetes/community/blob/master/contributors/design-proposals/api-proposal-design-template.md
146+
[design summary template]: https://github.com/kubernetes/community/blob/master/contributors/design-proposals/api-proposal-issue-template.md
147+
[API changes]: https://github.com/kubernetes/community/blob/master/contributors/devel/api_changes.md
148+
[contributing to SIG cli]: https://github.com/kubernetes/community/blob/master/sig-cli/contributing.md
149+
[kubernetes/kubernetes]: https://github.com/kubernetes/kubernetes/
150+
[kubernetes/features]: https://github.com/kubernetes/features/
151+
[kubernetes/kubernetes.github.io]: https://github.com/kubernetes/kubernetes.github.io/
152+
[kubernetes/community]: https://github.com/kubernetes/community/
153+
[API changes]: https://github.com/kubernetes/community/blob/master/contributors/devel/api_changes.md
154+
[API conventions]: https://github.com/kubernetes/community/blob/master/contributors/devel/api-conventions.md

‎contributors/devel/release/README.md

+55
Original file line numberDiff line numberDiff line change
@@ -114,3 +114,58 @@ During the code freeze period, fix any bugs discovered with you feature, and wri
114114
4. The docs lead will review your PR and give you feedback.
115115
5. Once approved, the docs lead will merge your PR into the release branch.
116116
6. When the release is cut, the docs lead will push the docs release branch to master, making your docs live on https://kubernetes.io/docs/.
117+
118+
# Kubernetes Release Process
119+
120+
## Development cycle
121+
122+
Pull requests for the next release are made against the master branch. New
123+
features slated for the release should have an issue filed in the [features repo].
124+
125+
## Feature freeze
126+
127+
Several weeks before the release is schedule to be cut, feature development will stop. Any
128+
features that have not been reviewed and approved before feature freeze will not make the
129+
release. At the feature freeze time, the focus will shift to completing the remaining tasks
130+
before the build has been validated as stable and ready to be publicly released. During this time,
131+
bug fixes should be focused on regressions and release-blocking issues. The majority of
132+
known issues present in previous releases will also not be accepted, since they are
133+
considered non-release blocking and should have been addressed during the normal
134+
development cycle.
135+
136+
*Code slush*
137+
138+
During the code slush period (1-2 weeks), the merge queue will only merge PRs labeled with the milestone
139+
for the upcoming release. This will include PRs that had been approved prior to the freature
140+
freeze deadline, but were not yet merged.
141+
142+
*Branching*
143+
144+
After the code slush period, a release branch will be cut. Parallel CI tests are
145+
run against the new release branch, and in order to get into the release, PRs
146+
must have both the *release-candidate* label and appropriate *milestone* set.
147+
148+
## Burn down
149+
150+
After feature freeze, regular burn down meetings are schedule to track the progress
151+
of the release blocking issues. Regular beta builds are cut and published
152+
during this period.
153+
154+
- Release branch tests are stable and passing on Jenkins
155+
- Client / server version skew tests are stable and passing on Jenkins
156+
- Upgrade / downgrade tests are stable and passing on Jenkins
157+
- Manual upgrade / downgrade tests have been run and passed
158+
- No open issues against the 1.x milestone
159+
- No open e2e flake issues against the 1.x milestone
160+
- No open features against the 1.x milestone
161+
162+
## Cutting the release
163+
164+
Once the build has been validated, a binary will be cut and published
165+
166+
- Write and publish release notes
167+
- Publish user facing documentation to the k8s.io site
168+
- Build and publish Kubernetes binaries
169+
- Announce release on social media
170+
171+
[features repo]: https://github.com/kubernetes/features/issues/

0 commit comments

Comments
 (0)