Merge pull request kubernetes#2 from derekwaynecarr/templates

Add initial enhancement templates

README.md

@@ -0,0 +1,69 @@
+# Enhancements Tracking and Backlog
+
+Enhancement tracking repository for OKD.
+
+Inspired by [Kubernetes
+enhancements](https://github.com/kubernetes/enhancements) process.
+
+This repository provides a rally point to discuss, debate, and reach consensus
+for how OKD [enhancements](./enhancements) are introduced.  OKD combines
+Kubernetes container orchestration services with a broad set of ecosystem
+components in order to provide an enterprise ready Kubernetes distribution built
+for extension.  OKD assembles innovation across a wide array of repositories and
+upstream communities.  Given the breadth of the distribution, it is useful to
+have a centralized place to describe OKD enhancements via an actionable design
+proposal.
+
+Enhancements may take multiple releases to ultimately complete.  Enhancements
+may be filed from anyone in the community, but require consensus from domain
+specific project maintainers in order to implement and accept into the release.
+
+## Is My Thing an Enhancement?
+
+A rough heuristic for an enhancement is anything that:
+
+- impacts how a cluster is operated
+- impacts upgrade/downgrade 
+- needs significant effort to complete
+- requires consensus/code across multiple domains/repositories
+- has phases of maturity (Dev Preview, Tech Preview, GA)
+- demands formal documentation to utilize
+
+It is unlikely to require an enhancement if it:
+
+- fixes a bug
+- adds more testing
+- internally refactors a code or component only visible to that components
+  domain
+- minimal impact to distribution as a whole
+
+If you are not sure if the proposed work requires an enhancement, file an issue
+and ask!
+
+## When to Create a New Enhancement
+
+Create an enhancement here once you:
+
+- have circulated your idea to see if there is interest
+- (optionally) have done a prototype in your own fork
+- have identified people who agree to work on and maintain the enhancement
+  - many enhancements will take several releases to complete  
+
+## Why are Enhancements Tracked
+
+As the project evolves, its important that the OKD community understands how we
+build, test, and document our work.  Individually it is hard to understand how
+all parts of the system interact, but as a community we can lean on each other
+to build the right design and approach before getting too deep into an
+implementation.
+
+## When to Comment on an Enhancement Issue
+
+Please comment on the enhancement issue to:
+- request a review or clarification on the process
+- update status of the enhancement effort
+- link to relevant issues in other repos
+
+Please do not comment on the enhancement issue to:
+- discuss a detail of the design, code or docs. Use a linked-to-issue or PR
+  design for that

enhancements/README.md

@@ -0,0 +1,39 @@
+# OKD Enhancement Proposals
+
+An OKD Enhancement Proposal is a way to propose, communicate, and coordinate on
+new efforts for the OKD project.
+
+It is inspired from our experience with the Kubernetes Enhancement process where
+many of our community participants collaborate each day.
+
+This process is evolving, but is mandatory for all enhancements beginning with
+release-4.3.
+
+## Quick start
+
+1. Socialize an idea with others.  Make sure others think the work is worth
+   doing, and are willing to review design and code changes required.
+2. Follow the process outlined in the [enhancement
+   template](enhancement-template.md)   
+
+## FAQs
+
+### Do I have to use the process?
+
+If the enhancement has broad scope, yes.  It helps everyone track why, when,
+how, and by whom work is done.
+
+### Why would I want to use the process?
+
+Provide a mechanism to communicate design and implementation strategies across
+the OKD community.
+
+### Do I put design in a particular directory?
+
+If it has broad impact, place it in the root of this directory.  If it's
+localized to a particular domain, find the appropriate directory.
+
+### My FAQ isn't answered here!
+
+Open an issue and ask or even better open a PR with a question and proposed
+answer.

enhancements/enhancements-template.md

@@ -0,0 +1,224 @@
+---
+title: Neat-Enhancement-Idea
+authors:
+  - "@janedoe"
+reviewers:
+  - TBD
+  - "@alicedoe"
+approvers:
+  - TBD
+  - "@oscardoe"
+creation-date: yyyy-mm-dd
+last-updated: yyyy-mm-dd
+status: provisional|implementable|implemented|deferred|rejected|withdrawn|replaced
+see-also:
+  - "/enhancements/this-other-neat-thing.md"  
+replaces:
+  - "/enhancements/that-less-than-great-idea.md"
+superseded-by:
+  - "/enhancements/our-past-effort.md"
+---
+
+# Title
+
+This is the title of the enhancement. Keep it simple and descriptive. A good
+title can help communicate what the enhancement is and should be considered as
+part of any review.
+
+The title should be lowercased and spaces/punctuation should be replaced with
+`-`.
+
+To get started with this template:
+1. **Pick a domain.** Find the appropriate domain to discuss your enhancement.
+1. **Make a copy of this template.** Copy this template into the directory for
+   the domain.
+1. **Fill out the "overview" sections.** This includes the Summary and
+   Motivation sections. These should be easy and explain why the community
+   should desire this enhancement.
+1. **Create a PR.** Assign it to folks with expertise in that domain to help
+   sponsor the process.
+1. **Merge at each milestone.** Merge when the design is able to transition to a
+   new status (provisional, implementable, implemented, etc.). View anything
+   marked as `provisional` as an idea worth exploring in the future, but not
+   accepted as ready to execute. Anything marked as `implementable` should
+   clearly communicate how an enhancement is coded up and delivered. If an
+   enhancement describes a new deployment topology or platform, include a
+   logical description for the deployment, and how it handles the unique aspects
+   of the platform. Aim for single topic PRs to keep discussions focused. If you
+   disagree with what is already in a document, open a new PR with suggested
+   changes.
+
+The `Metadata` section above is intended to support the creation of tooling
+around the enhancement process.
+
+## Release Signoff Checklist
+
+- [ ] Enhancement is `implementable`
+- [ ] Design details are appropriately documented from clear requirements
+- [ ] Test plan is defined
+- [ ] Graduation criteria for dev preview, tech preview, GA
+- [ ] User-facing documentation is created in [openshift/docs]
+
+## Summary
+
+The `Summary` section is incredibly important for producing high quality
+user-focused documentation such as release notes or a development roadmap. It
+should be possible to collect this information before implementation begins in
+order to avoid requiring implementors to split their attention between writing
+release notes and implementing the feature itself. 
+
+A good summary is probably at least a paragraph in length.
+
+## Motivation
+
+This section is for explicitly listing the motivation, goals and non-goals of
+this proposal. Describe why the change is important and the benefits to users.
+
+### Goals
+
+List the specific goals of the proposal. How will we know that this has succeeded?
+
+### Non-Goals
+
+What is out of scope for this proposal? Listing non-goals helps to focus discussion
+and make progress.
+
+## Proposal
+
+This is where we get down to the nitty gritty of what the proposal actually is.
+
+### User Stories [optional]
+
+Detail the things that people will be able to do if this is implemented.
+Include as much detail as possible so that people can understand the "how" of
+the system. The goal here is to make this feel real for users without getting
+bogged down.
+
+#### Story 1
+
+#### Story 2
+
+### Implementation Details/Notes/Constraints [optional]
+
+What are the caveats to the implementation? What are some important details that
+didn't come across above. Go in to as much detail as necessary here. This might
+be a good place to talk about core concepts and how they releate.
+
+### Risks and Mitigations
+
+What are the risks of this proposal and how do we mitigate. Think broadly. For
+example, consider both security and how this will impact the larger OKD
+ecosystem.
+
+How will security be reviewed and by whom? How will UX be reviewed and by whom?
+
+Consider including folks that also work outside your immediate sub-project.
+
+## Design Details
+
+### Test Plan
+
+**Note:** *Section not required until targeted at a release.*
+
+Consider the following in developing a test plan for this enhancement:
+- Will there be e2e and integration tests, in addition to unit tests?
+- How will it be tested in isolation vs with other components?
+
+No need to outline all of the test cases, just the general strategy. Anything
+that would count as tricky in the implementation and anything particularly
+challenging to test should be called out.
+
+All code is expected to have adequate tests (eventually with coverage
+expectations).
+
+### Graduation Criteria
+
+**Note:** *Section not required until targeted at a release.*
+
+Define graduation milestones.
+
+These may be defined in terms of API maturity, or as something else. Initial proposal
+should keep this high-level with a focus on what signals will be looked at to
+determine graduation.
+
+Consider the following in developing the graduation criteria for this
+enhancement:
+- Maturity levels - `Dev Preview`, `Tech Preview`, `GA`
+- Deprecation
+
+Clearly define what graduation means.
+
+#### Examples
+
+These are generalized examples to consider, in addition to the aforementioned
+[maturity levels][maturity-levels].
+
+##### Dev Preview -> Tech Preview
+
+- Ability to utilize the enhancement end to end
+- End user documentation, relative API stability
+- Sufficient test coverage
+- Gather feedback from users rather than just developers
+
+##### Tech Preview -> GA 
+
+- More testing (upgrade, downgrade, scale)
+- Sufficient time for feedback
+- Available by default
+
+**For non-optional features moving to GA, the graduation criteria must include
+end to end tests.**
+
+##### Removing a deprecated feature
+
+- Announce deprecation and support policy of the existing feature
+- Deprecate the feature
+
+### Upgrade / Downgrade Strategy
+
+If applicable, how will the component be upgraded and downgraded? Make sure this
+is in the test plan.
+
+Consider the following in developing an upgrade/downgrade strategy for this
+enhancement:
+- What changes (in invocations, configurations, API use, etc.) is an existing
+  cluster required to make on upgrade in order to keep previous behavior?
+- What changes (in invocations, configurations, API use, etc.) is an existing
+  cluster required to make on upgrade in order to make use of the enhancement?
+
+### Version Skew Strategy
+
+How will the component handle version skew with other components?
+What are the guarantees? Make sure this is in the test plan.
+
+Consider the following in developing a version skew strategy for this
+enhancement:
+- During an upgrade, we will always have skew among components, how will this impact your work?
+- Does this enhancement involve coordinating behavior in the control plane and
+  in the kubelet? How does an n-2 kubelet without this feature available behave
+  when this feature is used?
+- Will any other components on the node change? For example, changes to CSI, CRI
+  or CNI may require updating that component before the kubelet.
+
+## Implementation History
+
+Major milestones in the life cycle of a proposal should be tracked in `Implementation
+History`.
+
+## Drawbacks
+
+The idea is to find the best form of an argument why this enhancement should _not_ be implemented.
+
+## Alternatives
+
+Similar to the `Drawbacks` section the `Alternatives` section is used to
+highlight and record other possible approaches to delivering the value proposed
+by an enhancement.
+
+## Infrastructure Needed [optional]
+
+Use this section if you need things from the project. Examples include a new
+subproject, repos requested, github details, and/or testing infrastructure.
+
+Listing these here allows the community to get the process for these resources
+started right away.