Version KEP template and check for latest version in PR jobs

marosset commented 1 year ago

What would you like to be added:

We should version the README.md KEP template file and ensure that PRs that update the README files under https://github.com/kubernetes/enhancements/tree/master/keps have been updated to use the latest template.

Why is this needed:

Occasionally there are updates to the KEP templates in between releases and when the templates change between enhancement stages it:

Extra work on the enhancements team as they need to ensure that each enhancement opted into a release is using the latest template (which today is a manual process)
Confusion and risk for enhancement authors who may not have been aware that the templates changed, and updates are required when updating the KEPs to be included in a release.

https://kubernetes.slack.com/archives/CPNHUMN74/p1675716127904979 This also happened between v1.24 and v1.25 when the Test Plan section of the KEP template was updated.

Proposal

Add a version identified to the KEP template
Add a PR job to https://github.com/kubernetes/enhancements to validate that and PR updating a README.md file under https://github.com/kubernetes/enhancements/tree/master/keps is using the latest version of the template
Add a changelist file to track updates to the KEP template (so authors can easily see what has changed when they need to update their KEP

We could also consider adding logic to the PR job to ensure the ToC / basic structure of the README.md files containers required sections.

jeremyrickard commented 1 year ago

/sig architecture

jeremyrickard commented 1 year ago

/area enhancements

marosset commented 1 year ago

I added this to the SIG-arch enhancement sub project meeting on Feb 16 at 10:00 PST https://bit.ly/k8s-enhancements-agenda

marosset commented 1 year ago

@kikisdeliveryservice - have any other discussions happened since the sig-arch meeting on Feb 16? This issue came up again at the 1.27 mid-cycle retrospective

k8s-triage-robot commented 8 months ago

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

This bot triages un-triaged issues 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 as fresh with /remove-lifecycle stale
Close this issue with /close
Offer to help out with Issue Triage

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

/lifecycle stale

katcosgrove commented 7 months ago

This has come up again in the v1.30 cycle. Have we had any further discussion on the topic?

/remove-lifecycle stale

marosset commented 7 months ago

This has come up again in the v1.30 cycle. Have we had any further discussion on the topic?

/remove-lifecycle stale

I still this could add a lot of value and be helpful for the release team. I'm not sure who needs to give a go / no-go for the idea but can help out once we get that!

sreeram-venkitesh commented 5 months ago

Hi folks, I've been talking with @kikisdeliveryservice over the past couple of SIG Architecture enhancements subproject meetings about this issue. I have a POC for a script which compares a KEP with the KEP template file and lists the sections and the PRR questions which are present in the template but missing in the KEP readme. The idea I had was that enhancements shadows and production readinesss reviewers can run this locally to check if a KEP is up to date with the latest KEP template file in k/enhancements, like is it missing any questions from the PRR questionnaire etc. and the same script can be run as a CI job when new PRs are made updating KEP readme/kep.yaml files in k/enhancements. We don't need to introduce the KEP version in order to test this since the KEP template file can be the source of truth for now.

Apologies for not making it clear that I had started working on this issue! I've been working with the release enhancements team for the past two releases and wanted to try bring some changes to the process since I'm leading enhancements for v1.31!

sreeram-venkitesh commented 4 months ago

Hi folks, I've made some progress with writing a script similar to the CI jobs we have in k/enhancements to compare a KEP's readme file with the template. I have a few questions regarding where to take it from here:

I had a discussion with @enj at KubeCon about how it'd be easier for PRR reviewers and approvers to know if all of the questionnaire is answered properly and if the KEP is missing any questions from the latest template. Currently the script I have can identify if a KEP doesn't have any question/section that is present in the template. Do you think it'd be nice to have a feature to identify if the question/section has been answered or not?
Do we need to strictly check whether or not sections which are marked as optional in the template are there in the readme file or not?

I've made a video where I show the script in action, but I'd say this is still very early stage and it needs more work for us to be able to run it along with other CI jobs. I'd love to hear your feedback on this!

Demo video

k8s-triage-robot commented 1 month ago

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

This bot triages un-triaged issues 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 as fresh with /remove-lifecycle stale
Close this issue with /close
Offer to help out with Issue Triage

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

/lifecycle stale

sreeram-venkitesh commented 1 month ago

/remove-lifecycle stale

kubernetes / enhancements