First draft of a document outlining the api review process

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

@@ -0,0 +1,143 @@
+# Description of your API
+
+Initial API version: v1alpha1
+
+## Owners
+
+SIG owner: list of SIG that will own the design, implementation, and support
+Individual owners: list of individual GitHub users that will own the design, implementation, and support
+
+## Abstract
+
+4-8 sentence description of the problem and solution.  Bullet points welcome.
+
+## Motivation
+
+4-8 sentence of the current state and why it is insufficient.
+
+## Use cases
+
+Bullet point list of use cases this proposal is meant to address.
+
+- As a cluster administrator...
+- As a application developer...
+- As a Kubernetes extension developer...
+
+## Requirements
+
+Bullet point list of new API requirements.  Requirements will in part be driven by use
+cases, but may have additional engineering or interoperability requirements:
+
+- User requirement
+- Engineering requirement
+- Interoperability requirement
+
+## Overview subsequent versions
+
+Subsequent versions will require their own API proposals, however it is important to include
+the plans for them here to provide a broader picture.
+
+### Beta
+
+*Use cases*
+
+- Use cases for transitioning to Beta
+
+*Requirements*
+
+- Additional requirements for transitioning to Beta
+
+### GA
+
+*Use cases*
+
+- Use cases for transitioning to Beta
+
+*Requirements*
+
+- Additional requirements for transitioning to Beta
+
+## Dependencies and deadlines
+
+List of features that will depend on these changes.
+
+List of features that these changes will depend upon.
+
+**Include any deadlines that are related.** e.g. another feature depends on this and it is slated for 1.x.
+
+## Proposed changes for new types or existing types
+
+Declare the proposed Group / Version / Kind for any new types created as part of this proposal.
+
+Declare any new fields for existing types and their version.  Will the fields be added as first class fields or
+as annotations?
+
+Describe how any new types or fields will be used by the end user.  Include sample yaml config and full
+walkthrough examples of 1 or more usecases.
+
+### Defaulting
+
+Describe defaulting that will be done
+
+### Validation
+
+Describe validation the will be done
+
+### Patching lists - strategic merge keys
+
+For any list fields, describe whether they will be replaced when patched or merged.  If merged,
+describe the merge key that will be used.
+
+**mergeKeys must be unique and required for all elements in the list!**  Consequences of using a
+non-unique or optional merge key may be severe.
+
+### Controllers
+
+Describe any controllers that will be added or updated.
+
+### Subresources
+
+Describe any subresources that will be added.
+
+## Mandatory API pre-flight check list
+
+The following items must be considered and explained when adding or changing and API.
+
+### API convention deviations
+
+List and justify any deviations from [API conventions].  *None* is acceptable if
+there are no deviations.
+
+### Impact on backwards / forwards compatibility
+
+Describe any impact on backwards / forwards [compatibility].
+
+Known future incompatibility risks and mitigation.
+
+### Security, PII and authz
+
+Describe any security concerns or PII that is managed by the API.  Describe
+any special considerations that must be made for authentication or
+authorization.
+
+### Cli and client library considerations.
+
+Describe any interactions with the cli or client libraries.
+
+Is functionality in this API already present in the cli?  If so, was is the interaction and
+path forward?
+
+Is server side garbage collection needed / enabled?
+
+## Alternatives considered
+
+List alternative solutions to the use cases.  Include an analysis of any of
+the following that apply.
+
+- Client side solutions
+- Existing APIs or solutions that are similar
+- Existing workarounds - include solutions that compose existing APIs
+- Using ThirdPartyResources
+
+[API conventions]: https://github.com/kubernetes/community/blob/master/contributors/devel/api-conventions.md
+[compatibility]: https://github.com/kubernetes/community/blob/master/contributors/devel/api_changes.md#on-compatibility

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

@@ -0,0 +1,19 @@
+# Description of your API
+
+## Abstract
+
+4-8 sentence description of the problem and solution.  Bullet points welcome.
+
+## Motivation
+
+4-8 sentence of the current state and why it is insufficient.
+
+## Use cases
+
+Bullet point list of use cases this proposal is meant to address
+
+## Dependencies and deadlines
+
+List of features that will depend on these changes.
+
+List of features that these changes will depend upon.

contributors/devel/api_changes.md

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

contributors/devel/contributing-api-changes.md

@@ -0,0 +1,154 @@
+# Guidelines for contributing API changes
+
+## Overview
+
+Modifications to the core Kubernetes API have a material impact on the Kubernetes project, and
+undergo thorough review and discussion before they are accepted.  This document outlines the
+review process and what is expected of API contributors.
+
+## Process overview
+
+*Proposal process*
+
+All API changes require a formal proposal to be made, reviewed and accepted.  The proposal will be
+considered accepted once the proposal PR has been merged.
+
+*Feature process*
+
+All API changes require an issue to be filed in the [kubernetes/features] repo.  The
+issue will be used by release coordinators to track which features are slated for a
+release milestone.
+
+## Changes that qualify as API changes
+
+All changes to existing or new APIs are subject to the process outlined in this document.
+
+The following qualify as API changes:
+
+- Adding, removing, or modifying API types (e.g. through types.go, or by defining a new annotation)
+- Changing the version of an existing type (e.g. v1alpha1 to v1beta1)
+- Adding, removing, or modifying subresources for existing types. (e.g. /scale)
+- Material changes to how fields on existing types are interpreted / used - including, but not limited to
+  validation and defaulting of the fields.
+
+The following on their own do not qualify as API changes, but should follow the process defined by the related
+[special interest groups].
+
+- Adding or changing a command or flag to kubectl: See [contributing to SIG cli]
+- Building new command line tools: See [contributing to SIG cli]
+- Adding or changing a flag to kubelet: sig-node
+- Adding or changing a flag to apiserver: sig-api-machinery
+- Refactoring code
+- Building extensions
+
+## Life of an API change
+
+1. Start a discussion
+2. Write a short description
+3. Write a detailed design proposal in the [kubernetes/community] repo
+4. Schedule a design review
+5. File an issue in the [kubernetes/features] repo that links to the proposal
+6. Implement the proposal in the [kubernetes/kubernetes] repo
+7. Write user facing documentation on [kubernetes/kubernetes.github.io]
+
+### Start a discussion.
+
+Expected time for decision: 1-4 weeks (depending on the SIG and feature)
+
+Start a discussion with the relevant [special interest groups] that will [own] the changes.
+Depending on the SIG, this may be done via SIG meetings, email groups, slack channel, etc.
+
+### Write a short description
+
+Expected time for decision: 2 weeks
+
+Write a short description of the API changes by copying the [design summary template]
+into a new issue, and [@mention] @kubernetes/api-reviewers and the owning SIG reviewers
+group.
+
+Determine whether @kubernetes/api-reviewers is willing to accept a design proposal
+for your feature.  The answer could be "no, we don't want to solve this problem this way."
+or "no, this is something we want, but cannot commit the resources to reviewing it this release."
+
+### Write a detailed design proposal
+
+Expected time for initial feedback: 3-6 weeks
+
+Write a detailed design proposal PR using the [design proposal PR template].  [@mention]
+@kubernetes/api-reviewers and the appropriate SIGs on the PR and reference the original
+issue in the PR description.
+
+### Schedule a design review
+
+Expected time for next slot: 4-8 weeks
+
+Schedule a time for your design to be reviewed.
+
+See the current list of [design approvers](https://github.com/orgs/kubernetes/teams/api-approvers)
+
+**Note**: these are the current reviewers, we are still figuring out how to
+add/remove people to this list.  For more information, see the
+[governance discussion](https://groups.google.com/forum/#!topic/kubernetes-dev/4e8WOnMvZC0)
+
+### Implement the proposal
+
+Once the proposal has been accepted an merged, you can begin implementing the solution.
+
+## How to escalate
+
+Escalation should be done through the owning SIG.  If you need help getting attention, reach out to your
+SIG.
+
+## API change considerations
+
+First read the [API changes] document for background on how to make changes in the API.
+
+When writing a design proposal, you must consider the following:
+
+### API versions
+
+See [API versions] for details on the semantic meaning of the API versions.  Changes to how
+existing fields are validated, defaulted, or interpreted requires an API version change.
+
+### API groups
+
+It is important to pick the correct API group for your API.  This will ensure that it is discoverable
+by users and is maintained in concert with related APIs.  Current API groups:
+
+| Group  | Description |
+| ------ | ----------- |
+| abac   |             |
+| apps |   |
+| authentication |   |
+| authorization |   |
+| autoscaling |   |
+| batch |   |
+| certificates |   |
+| imagepolicy |   |
+| policy |   |
+| rbac |   |
+| settings  |   |
+| storage |   |
+
+
+## Related documents
+
+- [API changes]
+- [API conventions]
+- [OARP roles model](https://stumblingabout.com/tag/oarp/)
+- [RACI roles model](http://www.valuebasedmanagement.net/methods_raci.html)
+
+[API versions]: https://github.com/kubernetes/community/blob/master/contributors/devel/api_changes.md#alpha-beta-and-stable-versions
+[@mention]: https://help.github.com/articles/basic-writing-and-formatting-syntax/#mentioning-users-and-teams
+[own]: https://github.com/kubernetes/community/blob/master/contributors/sig-ownership.md
+[special interest groups]: https://github.com/kubernetes/community/blob/master/README.md#special-interest-groups-sig
+[design proposal PR template]: https://github.com/kubernetes/community/blob/master/contributors/design-proposals/api-proposal-design-template.md
+[design summary template]: https://github.com/kubernetes/community/blob/master/contributors/design-proposals/api-proposal-issue-template.md
+[API changes]: https://github.com/kubernetes/community/blob/master/contributors/devel/api_changes.md
+[contributing to SIG cli]: https://github.com/kubernetes/community/blob/master/sig-cli/contributing.md
+[kubernetes/kubernetes]: https://github.com/kubernetes/kubernetes/
+[kubernetes/features]: https://github.com/kubernetes/features/
+[kubernetes/kubernetes.github.io]: https://github.com/kubernetes/kubernetes.github.io/
+[kubernetes/community]: https://github.com/kubernetes/community/
+[API changes]: https://github.com/kubernetes/community/blob/master/contributors/devel/api_changes.md
+[API conventions]: https://github.com/kubernetes/community/blob/master/contributors/devel/api-conventions.md

contributors/devel/release/README.md

@@ -114,3 +114,58 @@ During the code freeze period, fix any bugs discovered with you feature, and wri
 4. The docs lead will review your PR and give you feedback.
 5. Once approved, the docs lead will merge your PR into the release branch.
 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/.
+
+# Kubernetes Release Process
+
+## Development cycle
+
+Pull requests for the next release are made against the master branch.  New
+features slated for the release should have an issue filed in the [features repo].
+
+## Feature freeze
+
+Several weeks before the release is schedule to be cut, feature development will stop.  Any
+features that have not been reviewed and approved before feature freeze will not make the
+release.  At the feature freeze time, the focus will shift to completing the remaining tasks
+before the build has been validated as stable and ready to be publicly released.  During this time,
+bug fixes should be focused on regressions and release-blocking issues.  The majority of
+known issues present in previous releases will also not be accepted, since they are
+considered non-release blocking and should have been addressed during the normal
+development cycle.
+
+*Code slush*
+
+During the code slush period (1-2 weeks), the merge queue will only merge PRs labeled with the milestone
+for the upcoming release.  This will include PRs that had been approved prior to the freature
+freeze deadline, but were not yet merged.
+
+*Branching*
+
+After the code slush period, a release branch will be cut.  Parallel CI tests are
+run against the new release branch, and in order to get into the release, PRs
+must have both the *release-candidate* label and appropriate *milestone* set.
+
+## Burn down
+
+After feature freeze, regular burn down meetings are schedule to track the progress
+of the release blocking issues.  Regular beta builds are cut and published
+during this period.
+
+- Release branch tests are stable and passing on Jenkins
+- Client / server version skew tests are stable and passing on Jenkins
+- Upgrade / downgrade tests are stable and passing on Jenkins
+- Manual upgrade / downgrade tests have been run and passed
+- No open issues against the 1.x milestone
+- No open e2e flake issues against the 1.x milestone
+- No open features against the 1.x milestone
+
+## Cutting the release
+
+Once the build has been validated, a binary will be cut and published
+
+- Write and publish release notes
+- Publish user facing documentation to the k8s.io site
+- Build and publish Kubernetes binaries
+- Announce release on social media
+
+[features repo]: https://github.com/kubernetes/features/issues/