Skip to content

Instantly share code, notes, and snippets.

@calebamiles

calebamiles/propose-adopting-rfc-process-for-kubernetes.md

Last active October 27, 2023 17:17
Show Gist options
  • Star 2 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save calebamiles/66386dfe9e00d90b5f1c621bd2899dbf to your computer and use it in GitHub Desktop.
Save calebamiles/66386dfe9e00d90b5f1c621bd2899dbf to your computer and use it in GitHub Desktop.
Download ZIP
proposal to adopt Rust's RFC process for Kubernetes
Raw
propose-adopting-rfc-process-for-kubernetes.md

Table of Contents

Goals

For the Release Team

  • there should be a place to write high quality release notes for upcoming changes
  • release notes should not be tied to an individual pull request (PR) given that large features may be split over multiple pull requests, especially when a change is back ported to older release branches
  • it should be easier to see whether an effort is being actively worked on or is still in the design phase
  • having to apply and reapply labels to issues changing their stability phase is mostly busy work
  • in general producing high quality blog posts requires summarizing technical information for less technical audiences, however, it is very difficult to source this material without contacting developers directly

For SIGs

  • there should be one place to link discussion threads about a change
  • SIGs should be able to approve or reject a proposed change, GitHub Issues have poor support for this given the limited number of states a GitHub Issue can be in {open|closed}
  • the design proposal for a requested change should be collocated with other information about a proposed change
  • high level design considerations should be discussed before detailed design and implementation plans
  • SIGs should only be required to update documents with useful information (e.g motivation for change, high level description of the change for release notes, high level design considerations, detailed design and implementation plan, stability criteria)

For contributors

  • improvement of git "muscles": familiarity with git is a skill that pays dividends while GitHub Issue management not so much

For everyone

  • we should avoid the use of proprietary tools (GitHub Issues, Google Sheets) as much as possible for an OSS project
  • it should be clear where the default place for efforts is tracked

Inspiration

The rust rfc process

Implementation

The idea of a "feature" will be expanded to a "request for comment" (RFC) process. The RFC process should be used to track all changes made to Kubernetes including development processes. An RFC should follow a standard template:

  1. links:

    • to implementation issue(s) (to be filled out later)
    • to PR for initial RFC (self reference to maintain link to PR discussion)
    • to PR for detailed design (self reference to maintain link to PR discussion)
    • to RFC specific mailing list discussion

  2. responsible SIG(s):

    • what SIG(s) are responsible for reviewing the change and owning its maintenance

  3. summary:

    • high level description of change which is high enough quality (grammar, spelling, clarity) to serve as the release note for the change

  4. motivation:

    • why do we believe this change is important
    • what benefits would the change provide
    • what are some examples of how the change would be consumed
    • high level design goals

  5. detailed design:

    • the technical information required for someone to implement the change
    • this section will probably vary significantly by SIG. For example the proposed changes to the API review process would likely fit within the detailed design section

  6. graduation criteria

    • what criteria will be used to evaluate the stability of a software feature introduction; what metrics will be used to evaluate the success of a process change

  7. drawbacks (optional):

    • what are the trade offs we know we are making with the accepted detailed design and why are we willing to accept them

  8. alternatives (optional):

    • is this RFC an extension or revision of a previously accepted RFC
    • are there other approaches to satisfying the same motivation

  9. unresolved questions (optional):

    • questions we could not reach consensus on but prevent implementation or things we just don't know yet

  10. mentor(s) (optional):

    • who is willing and able to offer support to the implementer(s) of the RFC so we can grow our community of contributors

I believe a reasonable expectation would be to have sections (1 - 4) fully filled out and agreed upon before an RFC is allowed to merge into kubernetes/rfcs which would signal acceptance of the problem identified in the motivation. After merge the author(s) of an RFC should work with the responsible SIG(s) to flesh out a detailed design (what we currently use design proposals for) and fill out sections (5 - 9) at which time work can begin on an implementation. Section (10) should be filled out at the same time as sections (1 - 4). Implementation of an RFC will involve one or more PRs which should reference the tracking issue(s) for the RFC.

Once the RFC process is finalized and approved kubernetes/features will be drained of existing issues and new changes will be approved through the RFC process.

Some examples of efforts which should follow the RFC process

  • any code change which would produce a release note
  • feature deprecation
  • changes which require node drain
  • changes to the release process
  • changes to test infrastructure
  • extraction of component from kubernetes/kubernetes
  • transfer of a repository to the {kubernetes, kubernetes-incubator} GitHub organization
  • governance changes
  • change to the RFC process itself
  • change will require operator action before or after upgrade

Tracking RFC progress through the release cycle

We are all greatly indebted to @idvoretskyi for all the hard done in maintaining the features tracking spreadsheet for the last several releases, however, given several requests for different ways to visualize efforts in progress it may be easier to store RFC progress snapshots in version control and allow community members to build tooling as desired.

It is proposed to extend the current set of issue status labels to cover the status of documentation (e.g docs/update-required, docs/in-review, docs/approved) working under the assumption that release notes will be derived from the RFC linked from the implementation issue.

It is also proposed to create a standard template for a release status document which will be checked into version control and shared with the community during the release cycle. These release status reports will list the status of the implementation of RFCs by SIG. The status reports will also have RFCs broken down by documentation status with the goal of driving the number of RFCs which are open per SIG as well as the number of RFCs required updated documentation burns down to zero as the release date approaches. The status reports should contain links to GitHub queries so that creating updated reports is simple.

Ideally the work to update the release status report will be shared among SIG members independent of the Release Team. It may also be possible to generalize the idea of a release status report in order to provide source material for efforts like this week in rust

Customization of the RFC process and exceptions

SIGs should be able to provide their own RFC process which is closely tailored to their domain, however, SIGs should specify in their chartering documents which RFC process they will use and what exceptions will be made for minor changes submitted with a simple PR

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment