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,245 @@
+# 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 and the 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/kubernetes 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 occurs, 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, frustration by contributors, and increased toil for the release team.
+
+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 update KEPs proactively and plan for release cycles
+* Improve the 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 opting-in process to a release will accept a specified file format (hereafter referred to as a `receipt`) containing metadata about 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 finalized 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 they feel they are not conforming to requirements. The team can ask the KEP Assignee to file an exception if the Enhancements Freeze deadline has been passed.
+
+After the 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 the 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 that release cycle's Docs deadline requirements.
+
+[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 Enhancement
+* 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
+    * Prioritize 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 / primary importance
+* Review Slipped Enhancements to support planning
+    * Determine what phase it missed
+    * Identify multiple slips / misses
+
+#### Enhancements Subteam
+
+* Pre enhancements Freeze (Enhancements Collection)
+  * Collect intentions/plans of KEP authors to graduate a KEP
+  * Ensure that those intents comply with 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 the progress of 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 in 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 contributors over several cycles.
+
+In 1.21, we'll focus on implementing much of this process manually, so there will be some burden 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 the receipts process.
+
+### 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 the manifest generation
+* Keeping KEP implementation history updated
+  * Requires intervention from a human and trust needs to be on the same person
+* Preventing enhancements to slip across release cycles
+* Ensuring enhancements don't permanently remain in the 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 enhancement 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 the 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 criteria 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"