From 774d738086a7208004a2cc73f237bd527a574b4a Mon Sep 17 00:00:00 2001 From: Sergey Kanzhelev Date: Thu, 8 Aug 2024 23:56:19 +0000 Subject: [PATCH] contributing KEPs in SIG Node: best practices --- sig-node/CONTRIBUTING.md | 124 +++++++++++++++++++++++++++++++++++++-- 1 file changed, 119 insertions(+), 5 deletions(-) diff --git a/sig-node/CONTRIBUTING.md b/sig-node/CONTRIBUTING.md index 94895af58..03e1746bc 100644 --- a/sig-node/CONTRIBUTING.md +++ b/sig-node/CONTRIBUTING.md @@ -2,7 +2,17 @@ Welcome! -## For Kubernetes Contributions +Thank you for your interest in contributing to SIG Node. SIG Node is one of the +biggest SIGs in Kubernetes. Reliability and performance of millions of nodes +running critical applications in production rely on the quality of your +contribution(s). The diversity of workloads, environments, and the scale SIG +Node needs to support makes every code change risky as all the side effects need +to be evaluated. + +Please make sure you understand and are up to the challenge. The contributing +instructions are designed to help you. + +## For Kubernetes Code Contributions Read the [Kubernetes Contributor Guide](https://github.com/kubernetes/community/tree/master/contributors/guide#contributor-guide). @@ -10,16 +20,120 @@ If you aspire to grow scope in the SIG, please review the [SIG Node contributor ### For Enhancements -SIG Node enhancements are available in the . +Find out if [your thing is an enhancement a.k.a KEP](https://github.com/kubernetes/enhancements/?tab=readme-ov-file#is-my-thing-an-enhancement). +A good way to do that is to open and issue and get feedback from SIG Node +reviewers and approvers. You can present your idea at a weekly +sig-node meeting to get interactive and more immediate feedback. -#### Helpful Links for Sig-Node +If you plan to contribute an enhancement, please prepare yourself for at least 1 +year of engagement. A KEP takes at least 4 kubernetes releases to move from +alpha to beta to GA. If there are API / kubelet skew considerations, it may take +even longer. SIG Node expects that contributors commit to taking a KEP to GA stage to avoid +[permanent betas](https://kubernetes.io/blog/2020/08/21/moving-forward-from-beta/#avoiding-permanent-beta). +It is always surprising how much work is needed to productize the feature after +it seems complete - addressing edge cases, comprehensive testing, and documentation +take a lot of effort. + +If you are not ready for this commitment, you can consider teaming up with other +contributors in the community or contribute to a KEP driven by somebody else. + +SIG Node enhancements are available: + +- Committed KEPs [directory](https://github.com/kubernetes/enhancements/tree/master/keps/sig-node) +- All open KEPs [tracking issues](https://github.com/kubernetes/enhancements/issues?q=is%3Aissue+is%3Aopen+label%3Asig%2Fnode+) + +Here are some best practices how to approach KEP development: +It is based on a [talk](https://kcsna2023.sched.com/event/1Sp9i/implementing-a-big-feature-on-an-example-of-a-sidecar-container-kep) +*"Implementing a big feature on an example of a Sidecar container KEP"* +([Recording](https://www.youtube.com/watch?v=c3iV8E8EDUA), [Slides](https://static.sched.com/hosted_files/kcsna2023/a0/KCS-NA-2023-ppt.pdf)). + +#### Before Starting + +- **Prove the need**: Clearly articulate the problem the KEP addresses, identify + the target audience, and demonstrate the community-wide benefits. +- **Secure sponsorship and reviews**: Find sponsors, reviewers, and approvers + early in the process to ensure alignment and avoid delays. +- **Show commitment**: Demonstrate dedication to the KEP's success by actively + working on its implementation and ensuring code quality. +- **Manage expectations**: The KEP process takes time, anticipate at least two + releases for beta and four for GA. + +At this stage the expectation is that the proposal is written in general-enough +terms as a Google Doc for easy commenting and fast collaborative editing. +Sharing the design document with `dev@kubernetes.io` for commenting and with SIG +members `kubernetes-sig-node@googlegroups.com` for commenting or in some cases +editing is a good practice. + +It is also very helpful to attend SIG Node weekly meeting to present your +proposal. Most of the time meeting agenda is open to discuss any proposals. +During the meeting you can gather initial feedback, find collaborators, and +secure sponsorship. + +#### API Design + +- **Define use cases and scope**: Enumerate specific use cases and define the + problem's boundaries to avoid scope creep. +- **Consider the bigger picture**: Illustrate how the KEP fits into the existing + Kubernetes design and how it will handle future requests. +- **Document decisions**: Record all design decisions, including pros, cons, and + responsible individuals. +- **Address potential misuse**: Anticipate potential abuse or misuse scenarios + and design the API to mitigate them. +- **Engage reviewers**: Utilize SIG experts for API pre-reviews and PRR + pre-reviews to gain support and streamline the review process. + +Kubernetes API is a main interface many users experience Kubernetes. API +approvers are often the most experienced community members, who can help ensure +the feature fit Kubernetes best practices, will not break compatibility, and +will fit nicely with other Kubernetes capabilities. Even if use cases were +approved by SIG Node approvers, API approvers may reject the proposal and ask to +redesign it. + +Some KEPs may go back and forth between use cases and API design for many +iterations. This often happens when use cases are not described completely or a +lot of context is lost in written feedback. If the KEP is going in those +circles, the recommendation is to request a meeting between SIG Approvers and +API approvers driven by KEP author. It may be a dedicated meeting or an invite +of API approvers to SIG Node weekly meeting or SIG Node approvers to API +meeting. + +Once API approval was received, SIG Node approvers will review it again as SIG +always has the last word in the feature design. + +Note, SIG approvers may request sign offs from other SIGs like Security, +Instrumentation, Storage, Networking, Windows, etc. The process of getting +approval is generally the same. + +#### Implementation + +- **Structure the implementation**: Divide the implementation into + pre-factoring, minimal complete product, and post-API changes for better + organization and review. +- **Isolate feature gate logic**: Ensure the mainline code remains unaffected + when the feature gate is disabled. +- **Adapt and adjust**: Be prepared to modify the KEP's scope or features based + on implementation challenges. +- **Collaborate effectively**: Maintain communication through group chats or + meetings and consider using a shared branch for better coordination. +- **Improve the codebase**: Leave the code in a better state than you found it + to facilitate future maintenance and enhance your credibility. + +By adhering to these best practices, you can increase the chances of your KEP +being successfully implemented and accepted. + +Sometimes SIG may over-commit on KEPs for the release. And if two big KEPs +touching the same code path, SIG may decide to only take one KEP for a release. +Even if this is the case, properly structured KEP implementation will ensure +that some progress was made for that release. + +### Helpful Links for SIG Node **Code**: -For general code organization, read [contributors/devel/README.md](../contributors/devel/README.md) for explaining things like +For general code organization, read [contributors/devel/README.md](../contributors/devel/README.md) to learn about things like `vendor/`, `staging`, etc. -* Kubelet +* kubelet * * * Probe: