Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add Receipts KEP #2167

Closed

Conversation

palnabarun
Copy link
Member

@palnabarun palnabarun commented Nov 26, 2020

KEP for #2140

@k8s-ci-robot k8s-ci-robot added do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. size/L Denotes a PR that changes 100-499 lines, ignoring generated files. labels Nov 26, 2020
@k8s-ci-robot k8s-ci-robot added kind/kep Categorizes KEP tracking issues and PRs modifying the KEP directory sig/architecture Categorizes an issue or PR as relevant to SIG Architecture. labels Nov 26, 2020
@palnabarun palnabarun self-assigned this Nov 26, 2020
@palnabarun palnabarun force-pushed the 2140-receipts-process branch 3 times, most recently from abcaab4 to 1254baf Compare November 26, 2020 07:38
- Minimal tooling to perform the defined process and validation of receipts
- Training/communicating the community about the changes to the process

#### Alpha -> Beta Graduation
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If this is data as input for new KEPs as a guideline, then I would add e2e tests cover some error paths of the feature


### Graduation Criteria

#### Alpha
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If this is data as input for new KEPs as a guideline, then I would add e2e tests cover the happy path

Copy link
Member

@kikisdeliveryservice kikisdeliveryservice left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

some quick thoughts and questions

#### Enhancements Subteam

* Pre enhancements Freeze (Enhancements Collection)
* Collect intents of KEP authors to graduate a KEP

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this isn't specific enough to the new process (as this same sentence holds true in the current process). Something referencing receipts and authors proactively opting in as this still sounds like the team is doing the leg work.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am planning to define what is collecting intent in the implementation section as well so that things are crystal clear. And, the enhancements team and/or other subteams of the release team do not need to do most of the leg work as is done today.

keps/sig-architecture/2140-receipts/README.md Outdated Show resolved Hide resolved
keps/sig-architecture/2140-receipts/README.md Outdated Show resolved Hide resolved
keps/sig-architecture/2140-receipts/README.md Outdated Show resolved Hide resolved
* 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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

is this just: keep the tracking sheet updated? or is this manifest something else?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a new YAML manifest that will get automagically generated from the files with kepctl or some other tool (we have a POC working on this already). Good question, so @palnabarun let's clarify this more.

keps/sig-architecture/2140-receipts/README.md Outdated Show resolved Hide resolved
keps/sig-architecture/2140-receipts/README.md Outdated Show resolved Hide resolved
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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Biggest risk is non-compliance, what is the mechanism for making it happen at each stage? There will be authors/sigs that do not participate for various reasons: capacity/lack of awareness/don't want to

Another Risk is that this isn't communicated effectively: this should also probably lay out how this is change of process is going to be communicated maybe in a section above?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have added a few points that I think could be a mitigation measure for non-compliance. Let's discuss further on those points.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Communication is a big one, we have had some trouble with getting everyone aware of PRR, for example.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Besides comms I would be ready to talk to the SIGs about it and help folks along where needed with the transition (extra large enhancements team)

* 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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

is this the implementation history in the receipt?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No. This is the implementation history of the KEP. Implementation history is a changelog throughout the lifecycle of the KEP and not just limited to the receipts in each release cycle.

Copy link
Contributor

@lasomethingsomething lasomethingsomething left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Heya, a bunch of typo fixes and nits.

The capitalization isn't consistent throughout, so maybe decide which terms you want to capitalize (Enhancements, Exception, At Risk when used as a status, etc.)

Great work!!

keps/sig-architecture/2140-receipts/README.md Outdated Show resolved Hide resolved
keps/sig-architecture/2140-receipts/README.md Outdated Show resolved Hide resolved
keps/sig-architecture/2140-receipts/README.md Outdated Show resolved Hide resolved
keps/sig-architecture/2140-receipts/README.md Outdated Show resolved Hide resolved
keps/sig-architecture/2140-receipts/README.md Outdated Show resolved Hide resolved
keps/sig-architecture/2140-receipts/README.md Outdated Show resolved Hide resolved
keps/sig-architecture/2140-receipts/README.md Outdated Show resolved Hide resolved
keps/sig-architecture/2140-receipts/README.md Outdated Show resolved Hide resolved
keps/sig-architecture/2140-receipts/README.md Outdated Show resolved Hide resolved
keps/sig-architecture/2140-receipts/README.md Outdated Show resolved Hide resolved
@palnabarun palnabarun force-pushed the 2140-receipts-process branch 2 times, most recently from c386ea5 to 2341522 Compare December 3, 2020 20:59
@justaugustus justaugustus added this to the keps-beta milestone Dec 4, 2020
@justaugustus
Copy link
Member

/assign
/hold for review

@k8s-ci-robot k8s-ci-robot added the do-not-merge/hold Indicates that a PR should not merge because someone has issued a /hold command. label Dec 4, 2020
@palnabarun palnabarun force-pushed the 2140-receipts-process branch 3 times, most recently from 717bb6e to ebd4d08 Compare December 8, 2020 15:56
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

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Communication is a big one, we have had some trouble with getting everyone aware of PRR, for example.

* Stricter gates have to be put for the process
* Exceptions only approach for a receipt to be added back to release cycle stage after the deadline
* Enhancement Team + Release Leads should have the final say on exceptions. The decision needs to be taken after considering the point of view of respective SIG leadership.
* Conflicts can arise when two people update/modify the same artifact
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also conflicts between places similar meta-data is stored. We have this issue with prr-approvers in kep.yaml as well as in the PRR approval request. We are going to eliminate the one in the kep.yaml. You'll want to make sure there are not redundant places people have to put in the meta-data, so you may want to remove milestones, latest-milestone from kep.yaml

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That is a nice point.

The ideology that we were following is that kep.yaml is the source of truth for all KEP related information. The receipts are just snaphots in time of what happened to a KEP. So, we can eventually deprecate the milestones struct and latest-milestones from kep.yaml once Receipts is up and running.

├── exception
├── OWNERS
├── proposed
│ └── 0004.yaml
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I still don't get the need for "proposed". Isn't an unmerged PR against "accepted" a proposal? Are we really going to git mv things around from accepted to at-risk? Wouldn't statuses in the receipt make more sense?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We did think about having the proposed state denoted as an unmerged PR having an accepted receipt v/s the proposed state.

We were thinking to reduce tracking of PRs as much as possible and having all information about the state in the repository as artifacts. The workflow leans towards having a Git heavy process v/s a GitHub heavy process.

Are we really going to git mv things around from accepted to at-risk? Wouldn't statuses in the receipt make more sense?

The receipts do have a tracking-status field. When moving between any of the buckets, that would be updated as well. After your suggestions, I am wondering if we should move over to a flat directory structure instead of bucketing as folders as well.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

+1 on John's idea, I think that would make the process simpler imo

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I commented above saying something similar. +1 flat structure. All the additional moves will just create additional PRs and complicate the process.


#### Docs Subteam

* Enhancements Freeze - Open Docs PR Deadline
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this is supposed to be the placeholder deadline, not enhancements freeze?

### 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.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it might be helpful to note here that in 1.21, we already started the opt-in process using the tracking sheet

* Stricter gates have to be put for the process
* Exceptions only approach for a receipt to be added back to release cycle stage after the deadline
* Enhancement Team + Release Leads should have the final say on exceptions. The decision needs to be taken after considering the point of view of respective SIG leadership.
* Conflicts can arise when two people update/modify the same artifact
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure if this is the right place, but there's also a problem/conflict that happens when all participating SIG of an enhancement does not agree to opt-in for the release. This happened in 1.21 and will continue to happen without communication happening across the SIGs

Copy link
Member

@kikisdeliveryservice kikisdeliveryservice left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

some questions/comments


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.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"After the Enhancements Collection period is completed..."

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"will need to" -> must


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.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"to see if" -> "to verify that"

* 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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

for clarity to reader:

k/w -> k/website

* Review Open/Proposed KEPs for my SIG
* Help plan reviews / dependencies
* Help identify major themes / release blogs
* Review At Risk KEPS for my SIG

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i think quoting is fine since that is done below

#### Docs Subteam

* Enhancements Freeze - Open Docs PR Deadline
* Ensure that the k/w PRs are populated in the KEPs

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

k/website


When a Kubernetes release begins, the release team currently begins enhancement collection by:

* Reviewing all open Enhancement issues

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

first two are no longer the process (list comes from sigs)


## 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.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

opt-in


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.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This feels like a regression from the current process where the sig submits the keps to the enhancements team for inclusion. Feels like the SIG should view/vet the filed receipts before the enhancements team starts looking. Otherwise we're back to authors -> team instead of author->sigs->team. unless receipts require a SIG ACK/NACK before team needs to do anything?

Copy link
Contributor

@jeremyrickard jeremyrickard Mar 12, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agree on that aspect. I think this should be "SIG Chair/TL (or delegate) creates the receipt".

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

+1 with a caveat, unless we want to replicate the sig structure into each release and copy owners files I'd say we ask for SIG chair/TL/delegates to ack on the PR if it is not filed by them.

The delegate could be seen as SIG liaison, PoC, or shepherd. That might be for a later convo though.

└── removed
└── 0003.yaml

$ kepctl accept 0004 --at-risk --release v1.22
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

we can use this after enhancements freeze to indicate when an enhancement is at risk of not making the code freeze. But, before enhancement freeze, I think I like John's idea of a simpler structure and open PR against the accepted directory. We can mark things at risk in the PR itself instead of keeping track here.


### Requesting an Exception for a KEP

To request an exception for the release, the responsible SIG will create a new PR that moves the receipt into the `exception` directory. A PR template in the `kubernetes/enhancement` repo will capture the relevant information for the exception request. The release team will approve the exception reqeust, but will require confirmation from any impacted reviewers on the PR before it is merged.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This removes the use of a mailing list for exceptions because SIGs will just create a PR, right? Is that going to be a problem? I thought transparency / communication with everyone in regards to exceptions were important?

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Rereading this and I have the same concern that we are removing the communication of the exception process and also removing the ability to explain why something was accepted and rejected to people who may not watch the repository closely.

Risks from cutting enhancement: (partial implementation, critical customer usecase, etc.)
```

If an exception request is not granted, the receipt is moved back to the `removed` directory. If the exception is granted, it is moved to the `at-risk` directory until the conditions that caused it to be removed are corrected. `kepctl` will provide convenience methods for this as well:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If an exception request is not granted, the receipt is moved back to the removed directory.

Is it really "moved back", or is it just that the exception request pull request is not approved and so the receipt never moves from the removed directory?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Normally, exceptions are requested for the enhancements that have been removed from the release. I think that's where "moved back" comes from which assumes that enhancement was already in the "removed" directory.


![Receipts State Diagram](state-diagram.png)

The flows shown in the state diagram are described in the sections below. Some of the flows described will have appropriate `kepctl` commands from the `Alpha` version itself. Other helper commands will be added and existing commands refined throughout the rollout process.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In some of these flows the pull request seems to be an important mechanism for discussion and debate. For example the exception request process, or even the proposal process.

However for some of these flows the pull request seems, effectively, a rubber stamp operation. For example an enhancement subteam member accepting a KEP, or moving an accepted KEP to at-risk. What would be the review process for these kinds of PRs? Is it expected that the enhancements team for a release will likely commit and review these internally. (i.e., one member executes kepctl and another approves and merges) or are even these "routine" operations intended to be points of community discussion and debate?

Comment on lines +228 to +233
title: Receipts process for tracking release enhancements
kep-number: 2140
owning-sig: sig-architecture
path: sig-architecture/2140-receipts
tracking-status: proposed
stage: alpha
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This was mentioned by others above, but isn't there a lot of duplication here?

  • tracking-status is duplicated from the location of the receipt itself
  • title, owning-sig, and path are all information that one can get from the KEP itself given the unique number?

So aren't only kep-number and stage relevant? Arguebly even the KEP number is in the name of the file. Are we trusting kepctl to keep it all in sync? What about changes to things like the KEP title during implementation? Would some system detect and rectify that?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd opt for file only and remove the additional directories. It seems like it'd just create additional repo traffic having to shuffle everything around. If the metadata is in place it should be easy to generate a list of what is at-risk etc.


### Proposing a KEP for a Release

A KEP author or SIG Chair/Tech Lead opts-in to a given release by creating the receipt document ([described above](#where-are-the-receipts-stored)) in the `proposed` directory for the specified release. The `latest-milestone` and `stage` should be updated in the associated `kep.yaml` file as well. This process can be done manually or with `kepctl`.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If a KEP missed the previous release (and so is in the removed directory of the previous release's structure), would the PR to propose it for the upcoming release add a whole new receipt, or move the receipt from the removed directory of the previous?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Whole new receipt, that will preserve the history and things being removed repeatedly be tracked.

└── 0005.yaml
```

The `OWNERS` file contains the Enhancements Team for that specific Release cycle.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is it just the enhancements subteam? What about the release lead/release lead shadows?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

good catch, I agree that it would be enhancements team + subteam + release lead/shadows.

Copy link
Member

@mrbobbytables mrbobbytables left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Made a few suggestion, but I think the big one that has been +1'ed is moving away from duplicating the directory structure with metadata. It will create a slew of additional PRs moving things around and if anyone links to the files in one of the directories before it moves it will break after its state is changed. I think it'd be better to use a flat file structure with the metadata being stored in the receipt.


This is also done simply by referencing the KEP from the kubernetes/kubernetes PR.

When a release cycle stage 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).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
When a release cycle stage 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).
When a release cycle stage such as enhancement freeze or code freeze occurs, the issue is updated to reflect inclusion or removal from the milestone, and the Release Team 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).

This is a bit of a nit, but "we" is not clear and could change depending on the reader for the KEP. I'd update it to reflect the actual team involved.


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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

+1 with a caveat, unless we want to replicate the sig structure into each release and copy owners files I'd say we ask for SIG chair/TL/delegates to ack on the PR if it is not filed by them.

The delegate could be seen as SIG liaison, PoC, or shepherd. That might be for a later convo though.

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

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Besides comms I would be ready to talk to the SIGs about it and help folks along where needed with the transition (extra large enhancements team)

Comment on lines +228 to +233
title: Receipts process for tracking release enhancements
kep-number: 2140
owning-sig: sig-architecture
path: sig-architecture/2140-receipts
tracking-status: proposed
stage: alpha
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd opt for file only and remove the additional directories. It seems like it'd just create additional repo traffic having to shuffle everything around. If the metadata is in place it should be easy to generate a list of what is at-risk etc.


### Proposing a KEP for a Release

A KEP author or SIG Chair/Tech Lead opts-in to a given release by creating the receipt document ([described above](#where-are-the-receipts-stored)) in the `proposed` directory for the specified release. The `latest-milestone` and `stage` should be updated in the associated `kep.yaml` file as well. This process can be done manually or with `kepctl`.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Whole new receipt, that will preserve the history and things being removed repeatedly be tracked.

==> Please Open a Pull Request to Finish Proposing This Enhancement for v1.22
```

A PR should then be opened by the KEP Author to complete the opt-in process. Once the PR is opened, a set of validation will run against the KEP based on the metadata in the receipt to ensure that all machine verifiable parts of the KEP are correctly populated for the specified stage. If required, when the validation completes, the enhancements team for that release will approve the PR. The KEP is now in the `proposed` state.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
A PR should then be opened by the KEP Author to complete the opt-in process. Once the PR is opened, a set of validation will run against the KEP based on the metadata in the receipt to ensure that all machine verifiable parts of the KEP are correctly populated for the specified stage. If required, when the validation completes, the enhancements team for that release will approve the PR. The KEP is now in the `proposed` state.
A PR should then be opened by the KEP Author to complete the opt-in process. Once the PR is opened, a validation process will run against the KEP based on the metadata in the receipt to ensure that all machine verifiable parts of the KEP are correctly populated for the specified stage. If required, when the validation completes, the enhancements team for that release will approve the PR. The KEP is now in the `proposed` state.

├── exception
├── OWNERS
├── proposed
│ └── 0004.yaml
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I commented above saying something similar. +1 flat structure. All the additional moves will just create additional PRs and complicate the process.

Copy link
Member

@justaugustus justaugustus left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(From Slack...)

Thoughts on this:

$ tree
.
├── approvals
│   ├── prod-readiness
│   │   └── 1337.yaml
│   └── security
│       └── 1337.yaml
├── proposals
│   ├── sig-awesome
│   │   └── 1337-the-best-proposal-ever
│   │       ├── kep.yaml
│   │       └── README.md
│   ├── sig-cool
│   │   └── receipts
│   │       └── v1.21
│   │           ├── 0001.yaml
│   │           ├── 0002.yaml
│   │           ├── 0003.yaml
│   │           ├── 0004.yaml
│   │           ├── 0005.yaml
│   │           ├── 0006.yaml
│   │           ├── 0007.yaml
│   │           ├── 0008.yaml
│   │           └── 0009.yaml
│   └── templates
│       ├── metadata.yaml
│       └── proposal.md
└── releases
    └── release-1.21
        └── receipt-manifest.yaml

...which may satisfy @kikisdeliveryservice's and @johnbelamaric's comments.

In that fake tree above:

  • a KEP author can submit a receipt to the relevant SIG sig-cool/receipts/v1.21/000{1..9}.yaml, which means the proposal of a Proposal's inclusion to the release is approved by the SIG
  • We (enhancements/RT enhancements/a bot delegate) run the kepctl receipts functionality over the repo and it generates the full manifest at releases/release-1.21/release-manifest.yaml

This:

  • doesn't erode SIG-level opt-in (per Kirsten's point)
  • removes the need for multiple subdirectories (per status) within the releases|receipts directory (per John's point)

- Training/communicating the community about the changes to the process

#### Alpha -> Beta Graduation (v1.22) (Proposed)

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we clarify here: does this mean that it's rolling out to authors/sigs? Because I think we need a bulletpoint covering a few actual authors/sigs opting in to test this before it becomes mandatory to be used?

Copy link
Member

@kikisdeliveryservice kikisdeliveryservice left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Q: the current state basically requires a min of 1 PR/ kep for it to become eligible for a release. Reading through this, it seems that a lot more PRs are generated via the receipt process. Can we quantify how many more PRs per kep are generated using this process?


### Requesting an Exception for a KEP

To request an exception for the release, the responsible SIG will create a new PR that moves the receipt into the `exception` directory. A PR template in the `kubernetes/enhancement` repo will capture the relevant information for the exception request. The release team will approve the exception reqeust, but will require confirmation from any impacted reviewers on the PR before it is merged.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Rereading this and I have the same concern that we are removing the communication of the exception process and also removing the ability to explain why something was accepted and rejected to people who may not watch the repository closely.



### Generating the release manifest

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

An issue that I see here is that there is no real-time one-stop artifact anymore. Per the below comment the manifest is manually generated, which means that it will frequently be stale, which seems like a downside as the spreadsheet was always the real-time status that anyone could refer to at any time.

If this is a yaml (not sure), we'll lose clickable links and easy color coding and stats.

* Enhancement Team + Release Leads should have the final say on exceptions. The decision needs to be taken after considering the point of view of respective SIG leadership.
* 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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm actually worried about the collision - people have no great way of coordinating this - it would be potentially 2 groups of people sigs and rt

* 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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I guess I'm wondering what function does the issue serve? Will they be eliminated? This seems worthwhile to address here since it's part of the existing process

==> Please Open a Pull Request to Finish Proposing This Enhancement for v1.22
```

A PR should then be opened by the KEP Author to complete the opt-in process. Once the PR is opened, a set of validation will run against the KEP based on the metadata in the receipt to ensure that all machine verifiable parts of the KEP are correctly populated for the specified stage. If required, when the validation completes, the enhancements team for that release will approve the PR. The KEP is now in the `proposed` state.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm wondering why a team member needs to approve the PR if it's only going to a proposed status? Seems like if a kep is being proposed and it passes all the automation it should go into the proposed bucket for further review?

└── 0003.yaml
```

Those receipts marked `at-risk`, will be periodically reviewed and moved to `accepted` once all required elements have been completed. In case, the requirements are not met by Enhancements Freeze, the

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

unfinished sentence above

@justaugustus
Copy link
Member

@kubernetes/enhancements -- what would we like next steps to be here?

@jeremyrickard
Copy link
Contributor

@kubernetes/enhancements -- what would we like next steps to be here?

I missed the last enhancements meeting, but it looks like there was a pretty lengthy discussion. Could @kikisdeliveryservice @palnabarun to summarize what the action/next steps are? Looks like some slack discussion too.

@kikisdeliveryservice
Copy link
Member

@kubernetes/enhancements -- what would we like next steps to be here?

I missed the last enhancements meeting, but it looks like there was a pretty lengthy discussion. Could @kikisdeliveryservice @palnabarun to summarize what the action/next steps are? Looks like some slack discussion too.

IIRC the next steps were that you and nabarun with input from enhancements were going to do some rethinking about the proposed receipts process and that there would be some discussion and refinement about the goals and methods of the receipts process overall.

@jeremyrickard
Copy link
Contributor

@kikisdeliveryservice would you say the input from enhancements is contained within the PR comments, or is it in a few different places? If it’s not contained within the PR, I’ll ask in the enhancements channel to have it added here so we have a single source of truth to work from.

@kikisdeliveryservice
Copy link
Member

@kikisdeliveryservice would you say the input from enhancements is contained within the PR comments, or is it in a few different places? If it’s not contained within the PR, I’ll ask in the enhancements channel to have it added here so we have a single source of truth to work from.

I don't think that the overall conversation re: rethinking happened yet so I don't really think there's something concrete to add that would be representative of anyone's thoughts. The discussion in the meeting was just briefly touching on the fact that there would be a future rethinking and discussion of the receipts process at some future date.

@jeremyrickard
Copy link
Contributor

@kikisdeliveryservice im not sure having a synchronous meeting to come up with the way forward / rethink the enchantments process is the best use of time to make progress at this point. Do you think you could distill (here) what you think the broad strokes and salient points are and we can go from there?

@kikisdeliveryservice
Copy link
Member

@kikisdeliveryservice im not sure having a synchronous meeting to come up with the way forward / rethink the enchantments process is the best use of time to make progress at this point. Do you think you could distill (here) what you think the broad strokes and salient points are and we can go from there?

As noted in the meeting notes, @palnabarun wanted an open discussion in slack, so I defer to him on that and will see where he wants to have this conversation.

@k8s-triage-robot
Copy link

The Kubernetes project currently lacks enough contributors to adequately respond to all issues and PRs.

This bot triages issues and PRs according to the following rules:

  • After 90d of inactivity, lifecycle/stale is applied
  • After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
  • After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

  • Mark this issue or PR as fresh with /remove-lifecycle stale
  • Mark this issue or PR as rotten with /lifecycle rotten
  • Close this issue or PR with /close
  • Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle stale

@k8s-ci-robot k8s-ci-robot added the lifecycle/stale Denotes an issue or PR has remained open with no activity and has become stale. label Aug 17, 2021
@justaugustus
Copy link
Member

@kubernetes/enhancements -- I'm closing this for now to take it off of the collective review stack.

Please feel free to reopen once we have some forward motion on next steps.

@justaugustus
Copy link
Member

/close

@k8s-ci-robot
Copy link
Contributor

@justaugustus: Closed this PR.

In response to this:

/close

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. kind/kep Categorizes KEP tracking issues and PRs modifying the KEP directory lifecycle/stale Denotes an issue or PR has remained open with no activity and has become stale. sig/architecture Categorizes an issue or PR as relevant to SIG Architecture. size/L Denotes a PR that changes 100-499 lines, ignoring generated files.
Projects
None yet
Development

Successfully merging this pull request may close these issues.