sig-architecture: add provisional Receipts KEP

Signed-off-by: Nabarun Pal <[email protected]>

Author: palnabarun

keps/sig-architecture/2140-receipts/README.md

@@ -0,0 +1,266 @@
+<!--
+**Note:** When your KEP is complete, all of these comment blocks should be removed.
+
+To get started with this template:
+
+- [ ] **Merge early and iterate.**
+  Avoid getting hung up on specific details and instead aim to get the goals of
+  the KEP clarified and merged quickly. The best way to do this is to just
+  start with the high-level sections and fill out details incrementally in
+  subsequent PRs.
+
+Just because a KEP is merged does not mean it is complete or approved. Any KEP
+marked as `provisional` is a working document and subject to change. You can
+denote sections that are under active debate as follows:
+
+```
+<<[UNRESOLVED optional short context or usernames ]>>
+Stuff that is being argued.
+<<[/UNRESOLVED]>>
+```
+-->
+# KEP-2140: Receipts process for tracking release enhancements
+
+<!-- toc -->
+- [Release Signoff Checklist](#release-signoff-checklist)
+- [Summary](#summary)
+- [Motivation](#motivation)
+  - [Goals](#goals)
+  - [Non-Goals](#non-goals)
+- [Proposal](#proposal)
+  - [User Stories](#user-stories)
+    - [KEP Authors](#kep-authors)
+      - [Proposing enhancements](#proposing-enhancements)
+      - [Filing an exception to Enhancements/Code Freeze](#filing-an-exception-to-enhancementscode-freeze)
+    - [API Reviewers](#api-reviewers)
+    - [SIG Chair / TLs / PMS](#sig-chair--tls--pms)
+    - [Enhancements Subteam](#enhancements-subteam)
+    - [Docs Subteam](#docs-subteam)
+  - [Notes/Constraints/Caveats](#notesconstraintscaveats)
+  - [Risks and Mitigations](#risks-and-mitigations)
+- [Design Details](#design-details)
+  - [Test Plan](#test-plan)
+  - [Graduation Criteria](#graduation-criteria)
+    - [Alpha](#alpha)
+    - [Alpha -&gt; Beta Graduation](#alpha---beta-graduation)
+    - [Future Graduations](#future-graduations)
+- [Implementation History](#implementation-history)
+<!-- /toc -->
+
+## Release Signoff Checklist
+
+Items marked with (R) are required *prior to targeting to a milestone / release*.
+
+- [x] (R) Enhancement issue in release milestone, which links to KEP dir in [kubernetes/enhancements] (not the initial KEP PR)
+- [ ] (R) KEP approvers have approved the KEP status as `implementable`
+- [ ] (R) Design details are appropriately documented
+- [-] (R) Test plan is in place, giving consideration to SIG Architecture and SIG Testing input
+- [x] (R) Graduation criteria is in place
+- [-] (R) Production readiness review completed
+- [-] Production readiness review approved
+- [-] "Implementation History" section is up-to-date for milestone
+- [-] User-facing documentation has been created in [kubernetes/website], for publication to [kubernetes.io]
+- [ ] Supporting documentation—e.g., additional design documents, links to mailing list discussions/SIG meetings, relevant PRs/issues, release notes
+
+[kubernetes.io]: https://kubernetes.io/
+[kubernetes/enhancements]: https://git.k8s.io/enhancements
+[kubernetes/kubernetes]: https://git.k8s.io/kubernetes
+[kubernetes/website]: https://git.k8s.io/website
+
+## Summary
+
+
+Introduce a new git based artifact, and supporting tooling, to support automated enhancement collection and tracking processes for Kubernetes Releases.
+
+
+## Motivation
+
+When a Kubernetes release begins, the release team currently begins enhancement collection by:
+
+* Reviewing all open Enhancement issues
+* Reviewing previous issue comments to determine activity
+* [Adding new comments, milestone and manually applying labels to get confirmation of inclusion in the release](https://github.com/kubernetes/enhancements/issues/1979#issuecomment-691394283)
+
+This is very time intensive for the release team and leads to many instances where notifications are missed, ultimately resulting in untracked Exceptions and rushed Exception Requests.
+
+During the implementation phase of the release, more comments and back and forth conversation occurs on the Enhancement issue, including:
+
+* tracking of kubernetes/kuberentes PRs[[1](https://github.com/kubernetes/enhancements/issues/1929#issuecomment-726228115)]
+* tracking kubernetes/website PRs[[2](https://github.com/kubernetes/enhancements/issues/2000#issuecomment-722752540)].
+
+This is also done simply by referencing the KEP from the kubernetes/kubernetes PR.
+
+When a milestone, such as enhancement freeze or code freeze occur, the issue is updated to reflect inclusion or removal from the milestone and we again leverage comments and manually applied labels to convey status, as an example consider [Build-in API Types Misses Code Freeze](https://github.com/kubernetes/enhancements/issues/1929#event-3991979549).
+
+Additionally, when an exception is required, this is [handled via email](https://groups.google.com/g/kubernetes-sig-release/c/eCk4Xyb58GQ/m/tjgEstjyAQAJ) and linked back to the issue via additional comments, such as [Built-in API Types Defaults Exception Granted](https://github.com/kubernetes/enhancements/issues/1929#issuecomment-727043537).
+
+Over time, this process becomes harder and harder to navigate, leading to decreased process clarity, leading to frustration by contributors and increased toil for the release team.
+
+In order to streamline this process and increase transparency, we will add a new git based artifact, hereafter referred to as a receipt. This receipt represents an opt-in promise/soft commitment from a SIG about KEPs they’re submitting to a specific release and will allow all tracking to occur via Git commits, rather than via issue comments, PR references and other non auditable mechanisms.
+
+### Goals
+
+* Support better KEP validation and automation through Git based process
+* Reduce friction and toil early in a release cycle
+* Eliminate instances where Enhancements aren't tracked due to miscommunication
+* Encourage SIGs to proactively update KEPs and plan for release cycles
+* Improve Exception process turning exception requests into a PR by the SIG with proper approvals
+* Increase KEP / Release transparency
+* Encourage better KEP implementation history updates
+
+
+### Non-Goals
+
+<!--
+What is out of scope for this KEP? Listing non-goals helps to focus discussion
+and make progress.
+-->
+
+
+## Proposal
+
+The process for opting in to a release will accept a specified file format (hereafter referred to as a `receipt`) containing metadata pertaining the KEP being enrolled. There would be one receipt per KEP per release cycle.
+
+The receipts would need to be created in the [k/enhancements][k-enhancements] repository. Once a KEP Author/Assignee creates a receipt on behalf of a SIG, it is understood that the feature has been soft opted-in to the release. The opt-in would be finalised only after the Enhancements Team verifies the laid out acceptance criteria.
+
+The Enhancements Team will continuously monitor the filed receipts during the Enhancements Collection period to verify the graduation requirements. The Enhancements Team will have the power to remove enhancements from the release if the team feels they are not conforming requirements. The team can ask the KEP Assignee to file an exception if Enhancements Freeze deadline has been passed.
+
+After collection of Enhancements is completed, KEP Assignees will need to update their receipts with the implementation PRs and documentation PRs (if any). KEP Assignees can update the receipt with the relevant PRs before Enhancements Freeze as well. The Enhancements Team will monitor the mentioned PRs for Code Freeze completion requirements. The team will have the right to ask the assignee to file for an exception or counsel the assignee whether they want to bump graduation of an enhancement to the next release cycle.
+
+The RT Docs team will monitor the mentioned documentation PRs to see if it conforms to the Docs deadline requirements of that release cycle.
+
+[See below][#design-details] for the receipt format and the process.
+
+### User Stories
+
+TODO: Mention the personas who are benefited through the improvements listed in this KEP
+TODO: Should we rewrite these into user story format? i.e. "As a SIG tech lead, I want to graduate a KEP in a specific release"
+
+#### KEP Authors
+
+##### Proposing enhancements
+
+* Specify New KEP for Release
+* Specify Graduation phase for existing KEP
+* Link / Report k/k PRs for a given Enhancment
+* Indicate k/w PRs for a given Enhancement
+
+##### Filing an exception to Enhancements/Code Freeze
+
+* Request Exception for Enhancement Freeze
+* Request Exception for Code Freeze
+
+#### API Reviewers
+
+* Review / Approve Exception Requests that need API Review
+    * Ensure reviewer bandwidth considered
+    * Priortize areas for upcoming releases
+
+#### SIG Chair / TLs / PMS
+
+* Review Open/Proposed KEPs for my SIG
+    * Help plan reviews / dependencies
+    * Help identify major themes / release blogs
+* Review At Risk KEPS for my SIG
+    * Help Prioritize last minute reviews
+* Review Exceptions for my SIG
+    * Determine release blocking / major importance
+* Review Slipped Enhancements to support planning
+    * Determine what phase it missed
+    * Identify multiple slips / misses
+
+#### Enhancements Subteam
+
+* Pre enhancements Freeze (Enhancements Collection)
+  * Collect intents of KEP authors to graduate a KEP
+  * Ensure that those intents comply to the graduation requirements
+  * Mark enhancements "At Risk" based on compliance with graduation requirements
+
+* At Enhancements Freeze
+  * Remove enhancements that do not comply with requirements
+
+* Enhancements Freeze - Code Freeze
+  * Ensure that the k/k PRs for the KEP are populated
+  * Mark enhancements "At Risk" based on progress on implementation
+  * Approve/Deny exceptions for Enhancements Freeze
+
+* Around Code Freeze
+  * Ensure that the enlisted k/k are merged
+  * Approve/Deny exceptions for Code Freeze
+
+* At Code Freeze
+  * Remove enhancements that have not completed requirements for Code Freeze
+
+* Throughout the Cycle
+  * Prepare a manifest of what's the status of enhancements at any point of time
+
+#### Docs Subteam
+
+* Enhancements Freeze - Open Docs PR Deadline
+  * Ensure that the k/w PRs are populated in the KEPs
+  * Communicate to SIG Docs about the expected review load
+
+* Open Docs PR Deadline - Docs Complete
+  * Mark enhancements "At Risk" if the following are true:
+    *  Docs PRs are not updated
+    *  The draft PRs have not been updated
+
+### Notes/Constraints/Caveats
+
+This KEP is based on a [high level plan](https://docs.google.com/document/d/1qnfXjQCBrikbbu9F38hdzWEo5ZDBd57Cqi0wG0V6aGc/edit#) incorporating feedback collected from release team members and contribtors over several cycles.
+
+In 1.21, we'll focus on implementing much of this process manually so there will be some burdon placed on people to create the appropriate YAML structure, but ideally these changes will free up time for people on the release team to work on automating
+
+### Risks and Mitigations
+
+* Conflicts can arise when two people update/modify the same artifact
+  * The team needs to have Git experience
+  * Only one person works on the artifacts at a time
+  * Communicate with each other when making changes
+  * Bots can eventually handle manifest generation
+* Keeping KEP implementation history updated
+  * Requires intervention from an human and trust needs to be on the same person
+* Preventing enhancements to slip across release cycles
+* Ensuring enhancements don't permanently remain in Beta stage
+* This KEP doesn't talk about KEP owners keeping enhancements issues up-to-date
+
+## Design Details
+
+TODO: - Write the folder structure and the format of receipts.
+
+### Test Plan
+
+This KEP entails a process change and hence the tooling to ease the processes will have necessary tests.
+
+### Graduation Criteria
+
+#### Alpha
+
+- Define the process to be followed by the SIGs when proposing an enhancent for the release
+- Define the process to be followed by the Enhancements subteam every release cycle
+- Minimal tooling to perform the defined process and validation of receipts
+- Training/communicating the community about the changes to the process
+
+#### Alpha -> Beta Graduation
+
+- Automation for the processes introduced in Alpha stage
+- Tooling should pull data from `kep.yaml` ensuring minimal diff between receipts and KEP metadata
+- Presubmit validations of receipts
+- Ease of use of all the proposed tooling
+
+#### Future Graduations
+
+- Solving woes of Docs team
+- Refining user experience based on feedback across release cycles
+
+## Implementation History
+
+- 2020-11-26: Provisional enhancement filed
+- 2020-MM-DD: Provisional enhancement accepted
+- 2020-MM-DD: Enhancement made implementable
+- 2020-MM-DD: Implementation started
+- 2020-MM-DD: Alpha criterion fulfilled
+- 2020-MM-DD: Rolled out for a release
+
+<!-- Links -->
+[k-enhancements]: https://git.k8s.io/enhancements

keps/sig-architecture/2140-receipts/kep.yaml

@@ -0,0 +1,21 @@
+title: Receipts process for tracking release enhancements
+kep-number: 2140
+authors:
+  - "@jeremyrickard"
+  - "@palnabarun"
+owning-sig: sig-architecture
+participating-sigs:
+  - sig-release
+status: provisional
+creation-date: 2020-11-24
+reviewers:
+  - "@justaugustus"
+approvers:
+  - "@justaugustus"
+see-also:
+  - "/keps/sig-architecture/617-improve-kep-implementation"
+  - "/keps/0001-kubernetes-enhancement-proposal-process.md"
+stage: alpha
+latest-milestone: "v1.21"
+milestone:
+  alpha: "v1.21"