First draft of a document outlining the api review process

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

@@ -0,0 +1,84 @@
+# Description of your Api
+
+## Owners
+
+Sig owner: list of sigs 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...
+
+## 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
+
+Declare the proposed Group / Version / Kind for any new types created as part of this proposal.
+
+Describe how the new types 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 performed on the new types
+
+### Validation
+
+Describe validation of fields on new types
+
+### 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.
+
+### Controllers
+
+Describe any controllers that will be added or updated.
+
+## Proposed changes to existing types
+
+Declare any new fields for existing types and their version.  Will the fields be added as first class fields or
+as annotations?
+
+### Defaulting
+
+Describe any defaulting for new fields
+
+### Validation
+
+Describe any validation for new fields
+
+### Controllers
+
+Describe changes to controllers for new fields
+
+### 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.
+
+## Impact on backwards / forwards compatibility
+
+Describe any impact on backwards / forwards compatibility
+
+## Alternatives considered
+
+List alternative solutions to the use cases.

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/contributing-api-changes.md

@@ -0,0 +1,134 @@
+# 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.
+
+## Changes that qualify as api changes
+
+Any 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
+
+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: sig-cli
+- Building new command line tools: 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
+4. Schedule a design review
+5. Implement the proposal
+
+### 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 slow for your design to be reviewed.
+
+Design approvers:
+- @smarterclayton
+- @bgrant
+- @thockin
+
+### 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 version semantics
+
+- *Alpha*
+
+Alpha versioned apis DO NOT guarantee backward compatibility between Kubernetes minor versions.
+
+- *Beta*
+
+Beta versioned apis DO guarantee backward compatibility between Kubernetes minor versions but
+are may have some known issues or unaddressed edge cases.  Beta apis may miss some functionality
+that would be needed to consider the api GA.
+
+- GA
+
+GA versioned apis DO guarantee backward compatibility between Kubernetes minor versions and
+are considered to be fully featured.  GA apis should have few known issues or edge cases.
+
+### Api group semantics
+
+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 |   |
+| componentconfig |   |
+| imagepolicy |   |
+| policy |   |
+| rbac |   |
+| settings  |   |
+| storage |   |
+
+[@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

contributors/sig-ownership.md

@@ -0,0 +1,51 @@
+# Sig Ownership Responsibilities
+
+## Overview
+
+This document describes the commitment that is undertaken by a [special interest group] as part of owning
+a feature or api change.  This applies to changes made to the [kubernetes/kubernetes] repo.
+
+## Design
+
+Depending on the size and impact of a feature, the design may need to go through a review process.  Changes
+that do not directly impact the api should follow the process defined by the owning sig.  Changes that
+do impact the api must go through an [api review] process.  Even non-api changes must think carefully about
+backwards compatibility to ensure clusters will continue to function correctly after an upgrade or downgrade.
+
+## Implementation
+
+Implementation includes writing and reviewing the code for the new feature.
+
+## Release tracking
+
+The owning special interest group must create an issue in [kubernetes/features] and respond to comments
+on the feature.  The feature issue MUST be updated with the current status within 1-2 days after feature freeze.
+
+## Testing
+
+Testing must be complete before the implementation is merged.
+
+### Unit + integration testing
+
+All new features must have appropriate coverage with unit + integration tests.
+
+### E2e testing
+
+E2e tests for a feature are owned by the sig that owns the feature, and must consistently pass.
+Tests that periodically fail must be fixed within the flake SLA defined for the project.
+
+### Upgrade testing
+
+Changes that could be impacted by upgrade / downgrades of a cluster must have automated tests to verify
+functionality during and after upgrade / downgrades.
+
+### Client-server version skew testing
+
+Any changes that break compatibility with client-server version skew tests of +-1 minor release must be resolved.
+
+## Documentation
+
+[special interest group]: https://github.com/kubernetes/community/blob/master/README.md#special-interest-groups-sig
+[kubernetes/kubernetes]: https://github.com/kubernetes/kubernetes
+[kubernetes/features]: https://github.com/kubernetes/features/
+[api review]: https://github.com/kubernetes/community/blob/master/contributors/contributing-api-changes.md