Kubernetes Contributors – Getting Started

Docs: Making your First Contribution

Mon, 01 Jan 0001 00:00:00 +0000

Your First Contribution

Find something to work on

Find something to work on

The first step to getting starting contributing to Kubernetes is to find something to work on. Help is always welcome, and no contribution is too small (but see below)!

Here are some things you can do today to get started contributing:

Help improve the Kubernetes documentation
Clarify code, variables, or functions that can be renamed or commented on
Write test coverage
Help triage issues

If the above suggestions don’t appeal to you, you can browse the issues labeled as a good first issue to see who is looking for help. Those interested in contributing without writing code can also find ideas in the Non-Code Contributions Guide.

Note: although contributions are welcome, beware that every pull request creates work for maintainers and costs for testing it. Fixing linter warnings is often not worth it because the existing code is fine. Always discuss with maintainers first before creating such PRs.

Find a good first topic

There are multiple repositories within the Kubernetes organization. Each repository has beginner-friendly issues that are a great place to get started on your contributor journey. For example, kubernetes/kubernetes has help wanted and good first issue labels for issues that don’t need high-level Kubernetes knowledge to contribute to. The good first issue label also indicates that Kubernetes Members have committed to providing extra assistance for new contributors. Another way to get started is to find a documentation improvement, such as a missing/broken link, which will give you exposure to the code submission/review process without the added complication of technical depth.

Issue Assignment in Github

When you’ve found an issue to work on, you can assign it to yourself.

Reply with /assign or /assign @yourself on the issue you’d like to work on
The K8s-ci-robot will automatically assign the issue to you.
Your name will then be listed under, Assignees.

Learn about SIGs

Some repositories in the Kubernetes Organization are owned by [Special Interest Groups], or SIGs.

The Kubernetes community is broken out into SIGs in order to improve its workflow, and more easily manage what is a very large community project. The developers within each SIG have autonomy and ownership over that SIG’s part of Kubernetes. Understanding how to interact with SIGs is an important part of contributing to Kubernetes. Check out the list of SIGs for contact information.

SIG structure

A SIG is an open, community effort.

Anybody is welcome to jump into a SIG and begin fixing issues, critique design proposals, and review code. SIGs have regular video meetings which everyone is welcome to attend. Each SIG has a Slack channel, meeting notes, and their own documentation that is useful to read and understand. There is an entire SIG (sig-contributor-experience) devoted to improving your experience as a contributor. If you have an idea for improving the contributor experience, please consider attending one of the Contributor Experience SIG’s weekly meetings.

Finding the appropriate SIG for your contribution and adding a SIG label will help you ask questions in the correct place and give your contribution higher visibility and a faster community response.

For Pull Requests, the automatically assigned reviewer will add a SIG label if you haven’t already done so.

For Issues, please note that the community is working on a more automated workflow. Since SIGs do not directly map onto Kubernetes subrepositories, it may be difficult to find which SIG your contribution belongs in. Review the list of SIGs to determine which SIG is most likely related to your contribution.

Example: if you are filing a CNI issue (that’s Container Networking Interface) you’d choose the Network SIG. Add the SIG label in a new comment on GitHub by typing the following:

/sig network

Follow the link in the SIG name column to reach each SIG’s README.

Most SIGs will have a set of GitHub Teams with tags that can be mentioned in a comment on issues and pull requests for higher visibility. If you are not sure about the correct SIG for an issue, you can try SIG-contributor-experience, or ask in Slack.

SIG-specific contributing guidelines

Some SIGs have their own CONTRIBUTING.md files, which may contain extra information or guidelines in addition to these general ones. These are located in the SIG-specific community directories:

File an Issue

Not ready to contribute code, but see something that needs work? While the community encourages everyone to contribute code, it is also appreciated when someone reports an issue. Issues should be filed under the appropriate Kubernetes subrepository. For example, a documentation issue should be opened in kubernetes/website. Make sure to adhere to the prompted submission guidelines while opening an issue. Check the issue triage guide for more information.

Docs: Contributing to Kubernetes

Mon, 01 Jan 0001 00:00:00 +0000

Contributing

Kubernetes is open source, but many of the people working on it do so as their day job. In order to avoid forcing people to be “at work” effectively 24/7, we want to establish some semi-formal protocols around development. Hopefully, these rules make things go more smoothly. If you find that this is not the case, please complain loudly.

As a potential contributor, your changes and ideas are welcome at any hour of the day or night, weekdays, weekends, and holidays. Please do not ever hesitate to ask a question or send a pull request.

Check out our community guiding principles on how to create great code as a big group.

Beginner focused information can be found below in Open a Pull Request and Code Review.

For quick reference on contributor resources, we have a handy contributor cheatsheet.

Communication

It is best to contact your SIG for issues related to the SIG’s topic. Your SIG will be able to help you much more quickly than a general question would.

For general questions and troubleshooting, use the standard lines of communication and work through the troubleshooting guide.

GitHub workflow

To check out code to work on, please refer to the GitHub Workflow Guide.

The full workflow for a pull request is documented here:

Kubernetes-specific github workflow.

That document is comprehensive and detailed, for purposes of a typical pull request we will cover the initial and simple use case here:

Opening a Pull Request

Pull requests are often called a “PR”. Kubernetes generally follows the standard github pull request process, but there is a layer of additional kubernetes specific (and sometimes SIG specific) differences:

The first difference you’ll see is that a bot will begin applying structured labels to your PR.

The bot may also make some helpful suggestions for commands to run in your PR to facilitate review.
These /command options can be entered in comments to trigger auto-labeling and notifications. Refer to its command reference documentation.

Common new contributor PR issues are:

Not having correctly signed the CLA ahead of your first PR. See the CLA page for troubleshooting help, in some cases you might need to file a ticket with the CNCF to resolve a CLA problem.
Finding the right SIG or reviewer(s) for the PR (see Code Review section) and following any SIG or repository specific contributing guidelines (see Learn about SIGs section)
Dealing with test cases which fail on your PR, unrelated to the changes you introduce (see Test Flakes)
Not following scalability good practices
Include mentions (like @person) and keywords which could close the issue (like fixes #xxxx) in commit messages.

Code Review

For a brief description of the importance of code review, please read On Code Review.
There are two aspects of code review: giving and receiving.

To make it easier for your PR to receive reviews, consider the reviewers will need you to:

Follow the project coding conventions
Write good commit messages
Break large changes into a logical series of smaller patches which individually make easily understandable changes, and in aggregate solve a broader issue
Label PRs with appropriate SIGs and reviewers: to do this read the messages the bot sends you to guide you through the PR process

Reviewers, the people giving the review, are highly encouraged to revisit the Code of Conduct as well as community expectations and must go above and beyond to promote a collaborative, respectful community. When reviewing PRs from others The Gentle Art of Patch Review suggests an iterative series of focuses which is designed to lead new contributors to positive collaboration without inundating them initially with nuances:

Is the idea behind the contribution sound?
Is the contribution architected correctly?
Is the contribution polished?

Note: if your pull request isn’t getting enough attention, you can use the #pr-reviews channel on Slack to get help finding reviewers.

Best practices

Write clear and meaningful git commit messages.
If the PR will completely fix a specific issue, include fixes #123 in the PR body (where 123 is the specific issue number the PR will fix. This will automatically close the issue when the PR is merged.
Make sure you don’t include @mentions or fixes keywords in your git commit messages. These should be included in the PR body instead.
When you make a PR for small change (such as fixing a typo, style change, or grammar fix), please squash your commits so that we can maintain a cleaner git history.
Make sure you include a clear and detailed PR description explaining the reasons for the changes, and ensuring there is sufficient information for the reviewer to understand your PR.
Additional Readings:

Testing

Testing is the responsibility of all contributors and is in part owned by all SIGs, but is also coordinated by sig-testing. Refer to the Testing Guide for more information.

There are multiple types of tests. The location of the test code varies with type, as do the specifics of the environment needed to successfully run the test:

Unit: These confirm that a particular function behaves as intended. Golang includes a native ability for unit testing via the testing package. Unit test source code can be found adjacent to the corresponding source code within a given package. For example: functions defined in kubernetes/cmd/kubeadm/app/util/version.go will have unit tests in kubernetes/cmd/kubeadm/app/util/version_test.go. These are easily run locally by any developer on any OS.
Integration: These tests cover interactions of package components or interactions between kubernetes components and some other non-kubernetes system resource (eg: etcd). An example would be testing whether a piece of code can correctly store data to or retrieve data from etcd. Integration tests are stored in kubernetes/test/integration/. Running these can require the developer set up additional functionality on their development system.
End-to-end (“e2e”): These are broad tests of overall system behavior and coherence. These are more complicated as they require a functional kubernetes cluster built from the sources to be tested. A separate document detailing e2e testing and test cases themselves can be found in kubernetes/test/e2e/.
Conformance: These are a set of testcases, currently a subset of the integration/e2e tests, that the Architecture SIG has approved to define the core set of interoperable features that all Kubernetes deployments must support. For more information on Conformance tests please see the Conformance Testing Document.

Continuous integration will run these tests either as pre-submits on PRs, post-submits against master/release branches, or both.
The results appear on testgrid.

sig-testing is responsible for that official infrastructure and CI. The associated automation is tracked in the test-infra repo. If you’re looking to run e2e tests on your own infrastructure, kubetest is the mechanism.

Security

Security Release Page - outlines the procedures for the handling of security issues.
Security and Disclosure Information - check this page if you wish to report a security vulnerability.

Documentation

Contributing to Documentation

Issues Management or Triage

Have you ever noticed the total number of open issues? Helping to manage or triage these open issues can be a great contribution and a great opportunity to learn about the various areas of the project. Triaging is the word we use to describe the process of adding multiple types of descriptive labels to GitHub issues, in order to speed up routing issues to the right folks. Refer to the Issue Triage Guidelines for more information.

Docs: Platforms Guide

Mon, 01 Jan 0001 00:00:00 +0000

Adding supported platforms

The default Kubernetes platform is linux/amd64. This platform has always been fully tested, and the build and release systems initially supported only this platform. SIG Release started an effort to support multiple architectures. As part of this effort, they added support in our build and release pipelines for the architectures arm, arm64, ppc64le and s390x on different operating systems like Linux, Windows and macOS.

The main focus was to have binaries and container images to be available for these architectures/operating systems. Contributors should be able to to take these artifacts and set up CI jobs to adequately test these platforms. Specifically to call out the ability to run conformance tests on these platforms.

Target of this document is to provide a starting point for adding new platforms to Kubernetes from a SIG Architecture and SIG Release perspective. This does not include release mechanics or supportability in terms of functionality.

Step 0: Engage with the community

The first step is to express the interest in adding a new platform or promoting one into a different Tier. This can be done by opening a GitHub issue in the SIG Release repository, attending the weekly SIG Release meetings or writing a message to the SIG Release mailing list.

The ultimate decision to approve or reject a platform will be done in the community as part of the standard lazy consensus. Even if all mentioned requirements for a platform are being met, it’s possible that external dependencies, infrastructure costs or anything else have influence on the maintainability of the platform.

Step 1: Building

The container image based build infrastructure should support this architecture. This implicitly requires the following:

golang should support the platform
All dependencies, whether vendored or run separately, should support this platform

In other words, anyone in the community should be able to use the SIG Release provided build tooling to generate all artifacts required to build Kubernetes.

More information about how to build Kubernetes can be found in the build documentation.

Step 2: Testing

It is not enough for builds to work as it gets bit-rotted quickly when vendoring in in new changes, update versions of things to be used etc. This means the project need a good set of tests that exercise a wide battery of jobs in this new architecture.

A good starting point from a testing perspective are:

unit tests
e2e tests
node e2e tests

This will ensure that community members can rely on these architectures on a consistent basis, which will give folks who are making changes a signal when they break things in a specific architecture.

This implies a set of folks who stand up and maintain both post-submit and periodic tests, watch them closely and raise the flag when things break. They will also have to help debug and fix any platform specific issues as well.

Creating custom testgrid dashboards can help to monitor platform specific tests.

Step 3: Releasing

The first 2 steps provide a reasonable expectation that there are people taking care of a supported platform and it works in a reproducible environment.

Getting to the next level is another big jump, because it needs to be ensured that real users can rely on the shipped artifacts.

This means specifically to add a set of CI jobs to the release-informing and release-blocking tabs of testgrid. The Kubernetes release team has a “CI signal” group that relies on the status(es) of these jobs to either ship or hold a release. Essentially, if things are mostly red with occasional green, it would be prudent to not even bother making this architecture as part of the release. CI jobs get added to release-informing first and when these get to a point where they work really well, then they get promoted to release-blocking.

The main problem here is once the project starts to ship something, users will start to rely on it. While it’s straight forward to setup a CI job as a one time thing, it’s a totally one to consistently maintain them over time. What SIG Release is looking for is a strong green CI signal for release managers to cut a release and for folks to be able to report problems and them getting addressed. This also includes conformance testing to ensure that the supported platform behaves as intended. This can be done by working with SIG Architecture as part of the conformance sub project in addition to testing and release.

Step 4: Finishing

If you got this far, you really have made it! You have a clear engagement with the community, you are working seamlessly with all the relevant SIGs, you have your content in the Kubernetes release and get end users to adopt your architecture. Having achieved conformance, you will gain conditional use of the Kubernetes trademark relative to your offerings.

Deprecating and removing supported platforms

Supported platforms may be considered as deprecated for various reasons, for example if they are being replaced by new ones, are not actively used or maintained any more. Deprecating an already supported platform has to follow a couple of steps:

The platform deprecation has been announced on the Kubernetes Announce mailing list and links to an Kubernetes GitHub issue for further discussions and consensus.
The deprecation will be active immediately after consensus has been reached at a set deadline. This incorporates approval from SIG Release and Architecture.
Removing the supported platform will be done in the beginning of the next minor (v1.N+1.0) release cycle, which means to:
- Update the Kubernetes build scripts to exclude the platform from all targets
- Update the kubernetes/sig-release repository to reflect the current set of supported platforms.

Please note that actively supported release branches are not affected by the removal. This ensures compatibility with existing artifact consumers on a best effort basis.

Docs: Pull Request Process

Mon, 01 Jan 0001 00:00:00 +0000

This doc explains the process and best practices for submitting a pull request to the Kubernetes project and its associated sub-repositories. It should serve as a reference for all contributors, and be useful especially to new and infrequent submitters.

Before You Submit a Pull Request

This guide is for contributors who already have a pull request to submit. If you’re looking for information on setting up your developer environment and creating code to contribute to Kubernetes, see the development guide.

First-time contributors should head to the Contributor Guide to get started.

Make sure your pull request adheres to our best practices. These include following project conventions, making small pull requests, and commenting thoroughly. Please read the more detailed section on Best Practices for Faster Reviews at the end of this doc.

Run Local Verifications

You can run these local verifications before you submit your pull request to predict the pass or fail of continuous integration.

Run and pass make verify (can take 30-40 minutes)
Run and pass make test
Run and pass make test-integration

The Pull Request Submit Process

Merging a pull request requires the following steps to be completed before the pull request will be merged automatically.

Open a pull request
- For kubernetes/kubernetes repository only: Add release notes if needed.
Follow the EasyCLA steps to sign the CLA (prerequisite)
Pass all e2e tests
Get all necessary approvals from reviewers and code owners

Marking Unfinished Pull Requests

If you want to solicit reviews before the implementation of your pull request is complete, you should hold your pull request to ensure that Tide does not pick it up and attempt to merge it. There are two methods to achieve this:

You may add the /hold or /hold cancel comment commands
You may add or remove a WIP or [WIP] prefix to your pull request title

The GitHub robots will add and remove the do-not-merge/hold label as you use the comment commands and the do-not-merge/work-in-progress label as you edit your title. While either label is present, your pull request will not be considered for merging.

Pull Requests and the Release Cycle

If a pull request has been reviewed but held or not approved, it might be due to the current phase in the Release Cycle. Occasionally, a SIG may freeze their own code base when working towards a specific feature or goal that could impact other development. During this time, your pull request could remain unmerged while their release work is completed.

If you feel your pull request is in this state, contact the appropriate SIG or SIG-Release for clarification.

Check the The Testing and Merge Workflow at the end of this document if you’re interested in the details on how exactly the automation processes pull requests.

Comment Commands Reference

The commands doc contains a reference for all comment commands.

Automation

The Kubernetes developer community uses a variety of automation to manage pull requests. This automation is described in detail in the automation doc.

How the e2e Tests Work

The end-to-end tests will post the status results to the pull request. If an e2e test fails, @k8s-ci-robot will comment on the pull request with the test history and the comment-command to re-run that test. e.g.

The following tests failed, say /retest to rerun them all.

Why was my pull request closed?

Pull requests older than 90 days will be closed. Exceptions can be made for pull requests that have active review comments, or that are awaiting other dependent pull requests. Closed pull requests are easy to recreate, and little work is lost by closing a pull request that subsequently needs to be reopened. We want to limit the total number of pull requests in flight to:

Maintain a clean project
Remove old pull requests that would be difficult to rebase as the underlying code has changed over time
Encourage code velocity

Why is my pull request not getting reviewed?

A few factors affect how long your pull request might wait for review.

If it’s the last few weeks of a milestone, we need to reduce churn and stabilize.

Or, it could be related to best practices. One common issue is that the pull request is too big to review. Let’s say you’ve touched 39 files and have 8657 insertions. When your would-be reviewers pull up the diffs, they run away - this pull request is going to take 4 hours to review and they don’t have 4 hours right now. They’ll get to it later, just as soon as they have more free time (ha!).

There is a detailed rundown of best practices, including how to avoid too-lengthy pull requests, in the next section.

But, if you’ve already followed the best practices and you still aren’t getting any pull request love, here are some things you can do to move the process along:

Make sure that your pull request has an assigned reviewer (assignee in GitHub). If not, reply to the pull request comment stream asking for a reviewer to be assigned. This is done via a bot command (the bot may have suggestions for this) and looks like this: /assign @username.
Ping the assignee (@username) on the pull request comment stream, and ask for an estimate of when they can get to the review.
Ping the assignee on Slack. Remember that a person’s GitHub username might not be the same as their Slack username.
Ping the assignee by email (many of us have publicly available email addresses).
If you’re a member of the organization ping the team (via @team-name) that works in the area you’re submitting code to.
If you have fixed all the issues from a review, and you haven’t heard back, you should ping the assignee on the comment stream with a “please take another look” (PTAL) or similar comment indicating that you are ready for another review.
If you still don’t hear back, post a link to the pull request in the #pr-reviews channel on Slack to find additional reviewers.

Read on to learn more about how to get faster reviews by following best practices.

Best Practices for Faster Reviews

Most of this section is not specific to Kubernetes, but it’s good to keep these best practices in mind when you’re making a pull request.

You’ve just had a brilliant idea on how to make Kubernetes better. Let’s call that idea Feature-X. Feature-X is not even that complicated. You have a pretty good idea of how to implement it. You jump in and implement it, fixing a bunch of stuff along the way. You send your pull request - this is awesome! And it sits. And sits. A week goes by and nobody reviews it. Finally, someone offers a few comments, which you fix up and wait for more review. And you wait. Another week or two go by. This is horrible.

Let’s talk about best practices so your pull request gets reviewed quickly.

Familiarize yourself with project conventions

Is the feature wanted? File a Kubernetes Enhancement Proposal

Are you sure Feature-X is something the Kubernetes team wants or will accept? Is it implemented to fit with other changes in flight? Are you willing to bet a few days or weeks of work on it?

It’s better to get confirmation beforehand.

When you want to make a large or otherwise significant change, you should follow the Kubernetes Enhancement Proposal process.

Even for small changes, it is often a good idea to gather feedback on an issue you filed, or even simply ask in the appropriate SIG’s Slack channel to invite discussion and feedback from code owners. Here’s a list of SIGs, this includes their public meetings.

KISS, YAGNI, MVP, etc.

Sometimes we need to remind each other of core tenets of software design - Keep It Simple, You Aren’t Gonna Need It, Minimum Viable Product, and so on. Adding a feature “because we might need it later” is antithetical to software that ships. Add the things you need NOW and (ideally) leave room for things you might need later - but don’t implement them now.

Smaller Is Better: Small Commits, Small Pull Requests

Small commits and small pull requests get reviewed faster and are more likely to be correct than big ones.

Attention is a scarce resource. If your pull request takes 60 minutes to review, the reviewer’s eye for detail is not as keen in the last 30 minutes as it was in the first. It might not get reviewed at all if it requires a large continuous block of time from the reviewer.

Breaking up commits

Break up your pull request into multiple commits, at logical break points.

Making a series of discrete commits is a powerful way to express the evolution of an idea or the different ideas that make up a single feature. Strive to group logically distinct ideas into separate commits.

For example, if you found that Feature-X needed some prefactoring to fit in, make a commit that JUST does that prefactoring. Then make a new commit for Feature-X.

Strike a balance with the number of commits. A pull request with 25 commits is still very cumbersome to review, so use your best judgment.

Breaking up Pull Requests

Or, going back to our prefactoring example, you could also fork a new branch, do the prefactoring there and send a pull request for that. If you can extract whole ideas from your pull request and send those as pull requests of their own, you can avoid the painful problem of continually rebasing.

Kubernetes is a fast-moving codebase - lock in your changes ASAP with your small pull request, and make merges be someone else’s problem.

Multiple small pull requests are often better than multiple commits. Don’t worry about flooding us with pull requests. We’d rather have 100 small,obvious pull requests than 10 unreviewable monoliths.

We want every pull request to be useful on its own, so use your best judgment on what should be a pull request vs. a commit.

As a rule of thumb, if your pull request is directly related to Feature-X and nothing else, it should probably be part of the Feature-X pull request. If you can explain why you are doing seemingly no-op work (“it makes the Feature-X change easier, I promise”) we’ll probably be OK with it. If you can imagine someone finding value independently of Feature-X, try it as a pull request. (Do not link pull requests by # in a commit description, because GitHub creates lots of spam. Instead, reference other pull requests via the pull request your commit is in.)

Open a Different Pull Request for Fixes and Generic Features

Put changes that are unrelated to your feature into a different pull request.

Often, as you are implementing Feature-X, you will find bad comments, poorly named functions, bad structure, weak type-safety, etc.

You absolutely should fix those things (or at least file issues, please) - but not in the same pull request as your feature. Otherwise, your diff will have way too many changes, and your reviewer won’t see the forest for the trees.

Look for opportunities to pull out generic features.

For example, if you find yourself touching a lot of modules, think about the dependencies you are introducing between packages. Can some of what you’re doing be made more generic and moved up and out of the Feature-X package? Do you need to use a function or type from an otherwise unrelated package? If so, promote! We have places for hosting more generic code.

Likewise, if Feature-X is similar in form to Feature-W which was checked in last month, and you’re duplicating some tricky stuff from Feature-W, consider prefactoring the core logic out and using it in both Feature-W and Feature-X. (Do that in its own commit or pull request, please.)

Don’t Open Pull Requests That Span the Whole Repository

Often a new contributor will find some problem that exists in many places across the main kubernetes/kubernetes repository, and file a PR to fix it everywhere at once. Maybe there’s a cool new function in the latest golang release that everyone ought to be using, or a recently-deprecated function that ought to be replaced with calls to its replacement. Sometimes a contributor will run a linter or security scanner across the code to find problems, or fix a particular spelling mistake in comments or variable names. (It’s “deprecated”, not “depreciated”!)

The problem with this approach is that different parts of kubernetes/kubernetes are maintained by different SIGs, and so changes to those different parts require approvals from different people. A PR containing 20 one-line changes scattered across the repository could end up needing 5 or 10 approvals or more before it can be merged. (While there are a handful of people who can approve changes across large portions of the repository, those are generally the people who are the most busy and hardest to get reviews from, especially when you’re a new contributor with no connections within the community yet.)

The effort required to review such sweeping changes might not be worth it, see “large or automatic edits” below.

If you really want to try to get such a PR merged, your best bet is to break up the PR into separate PRs for each SIG whose code it touches. You can look at the OWNERS files in a directory (or its parent directory) to see who owns that code, and then group the changes together accordingly (e.g., with one PR touching files in cmd/kube-proxy and pkg/util/iptables, which are owned by SIG Network, and another PR touching files in pkg/kubelet and pkg/controller/nodelifecycle, which are owned by SIG Node.)

Comments Matter

In your code, if someone might not understand why you did something (or you won’t remember why later), comment it. Many code-review comments are about this exact issue.

If you think there’s something pretty obvious that we could follow up on, add a TODO.

Read up on GoDoc - follow those general rules for comments.

Test

Nothing is more frustrating than starting a review, only to find that the tests are inadequate or absent. Very few pull requests can touch the code and NOT touch tests.

If you don’t know how to test Feature-X, please ask! We’ll be happy to help you design things for easy testing or to suggest appropriate test cases.

Squashing

Your reviewer has finally sent you feedback on Feature-X.

Make the fixups, and don’t squash yet. Put them in a new commit, and re-push. That way your reviewer can look at the new commit on its own, which is much faster than starting over.

We might still ask you to clean up your commits at the very end for the sake of a more readable history, but don’t do this until asked: typically at the point where the pull request would otherwise be tagged LGTM.

Each commit should have a good title line (<70 characters) and include an additional description paragraph describing in more detail the change intended.

For more information, see squash commits.

General squashing guidelines:

Sausage => squash

Do squash when there are several commits to fix bugs in the original commit(s), address reviewer feedback, etc. Really we only want to see the end state, and commit message for the whole pull request.

Layers => don’t squash

Don’t squash when there are independent changes layered to achieve a single goal. For instance, writing a code munger could be one commit, applying it could be another, and adding a precommit check could be a third. One could argue they should be separate pull requests, but there’s really no way to test/review the munger without seeing it applied, and there needs to be a precommit check to ensure the munged output doesn’t immediately get out of date.

Note: you can also use the tide/merge-method-squash label on your PR to let the bot handle squashing all commits, which can be done by commenting /label tide/merge-method-squash. As opposed to squashing by hand, this will prevent removal of the lgtm label (if already applied) and re-run of the CI tests. Although, if this label is used, please know the following:

All commit messages will be squashed and combined and the final commit message will be a combination of all commit messages according to how GitHub generates the message for a squash merge, for example, if this is the lifecycle of your PR:
```
# commit 1
Original commit msg
Some useful information
Some more useful information
```
```
# commit 2
Address review comments
```
```
# commit 3
Fix test
```
After applying the label, if the PR is merged, the final commit message will end up being:
```
Title of your PR (#PR-number)
* Original commit msg
Some useful information
Some more useful information
* Address review comments
* Fix test
```
Since commit messages are meant to be a record of the “why” and “what” of your changes, having messages like “Address review comments” in the final commit message adds no real value in terms of communicating the “what"s and “why"s of your change. Please see Commit Message Guidelines for more details on writing better commit messages.

Using this label can help when squashing by hand is considered too challenging or not worth the extra effort. It can also speed up merging because squashing by hand implies getting another LGTM from a reviewer and re-run of the CI tests.

Commit Message Guidelines

PR comments are not represented in the commit history. Commits and their commit messages are the “permanent record” of the changes being done in your PR and their commit messages should accurately describe both what and why it is being done.

Commit messages are comprised of two parts; the subject and the body.

The subject is the first line of the commit message and is often the only part that is needed for small or trivial changes. Those may be done as “one liners” with the git commit -m or the --message flag, but only if the what and especially why can be fully described in that few words.

The commit message body is the portion of text below the subject when you run git commit without the -m flag which will open the commit message for editing in your preferred editor. Typing a few further sentences of clarification is a useful investment in time both for your reviews and overall later project maintenance.

This is the commit message subject
Any text here is the commit message body
Some text
Some more text
...
# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
#
# On branch example
# Changes to be committed:
# ...
#

Use these guidelines below to help craft a well formatted commit message. These can be largely attributed to the previous work of Chris Beams, Tim Pope, Scott Chacon and Ben Straub.

Try to keep the subject line to 50 characters or less; do not exceed 72 characters

The 50 character limit for the commit message subject line acts as a focus to keep the message summary as concise as possible. It should be just enough to describe what is being done.

The hard limit of 72 characters is to align with the max body size. When viewing the history of a repository with git log, git will pad the body text with additional blank spaces. Wrapping the width at 72 characters ensures the body text will be centered and easily viewable on an 80-column terminal.

Providing additional context

You can provide additional context with fewer characters by prefixing your commit message with the kind or area that your PR is impacting. These are commonly used labels that other members of the Kubernetes community will understand.

Examples:

cleanup: remove unused portion of script foo
deprecation: add notice for bar feature removal in future release
etcd: update default server to 3.4.7
kube-proxy: add a test case for HostnameOverride

These can serve as a good subject before expanding further on the what and why within the commit message body.

The first word in the commit message subject should be capitalized unless it starts with a lowercase symbol or other identifier

The commit message subject is like an abbreviated sentence. The first word should be capitalized unless the message begins with symbol, acronym or other identifier such as kind or area that would regularly be lowercase.

Do not end the commit message subject with a period

This is primary intended to serve as a space saving measure, but also aids in driving the subject line to be as short and concise as possible.

Use imperative mood in your commit message subject

Imperative mood can be be thought of as a “giving a command”; it is a present-tense statement that explicitly describes what is being done.

Good Examples:

Fix x error in y
Add foo to bar
Revert commit “baz”
Update pull request guidelines

Bad Examples

Fixed x error in y
Added foo to bar
Reverting bad commit “baz”
Updating the pull request guidelines
Fixing more things

A general guideline from Chris Beams on forming an imperative commit subject is it should complete this sentence:

If applied, this commit will <your subject line here>

Examples:

If applied, this commit will Fix x error in y
If applied, this commit will Add foo to bar
If applied, this commit will Revert commit “baz”
If applied, this commit will Update the pull request guidelines

Add a single blank line before the commit message body

Git uses the blank line to determine which portion of the commit message is the subject and body. Text preceding the blank line is the subject, and text following is considered the body.

Wrap the commit message body at 72 characters

The default column width for git is 80 characters. Git will pad the text of the message body with an additional 4 spaces when viewing the git log. This would leave you with 76 available spaces for text, however the text would be “lop-sided”. To center the text for better viewing, the other side is artificially padded with the same amount of spaces, resulting in 72 usable characters per line. Think of them as the margins in a word doc.

Do not use GitHub keywords or (@)mentions within your commit message

GitHub Keywords

Using GitHub keywords followed by a #<issue number> reference within your commit message will automatically apply the do-not-merge/invalid-commit-message label to your PR preventing it from being merged.

GitHub keywords in a PR to close issues is considered a convenience item, but can have unexpected side-effects when used in a commit message; often closing something they shouldn’t.

Blocked Keywords:

close
closes
closed
fix
fixes
fixed
resolve
resolves
resolved

(@)Mentions

(@)mentions within the commit message will send a notification to that user, and will continually do so each time the PR is updated.

Use the commit message body to explain the what and why of the commit

Commits and their commit messages are the “permanent record” of the changes being done in your PR. Describing why something has changed and what effects it may have. You are providing context to both your reviewer and the next person that has to touch your code.

If something is resolving a bug, or is in response to a specific issue, you can link to it as a reference with the message body itself. These sorts of breadcrumbs become essential when tracking down future bugs or regressions and further help explain the “why” the commit was made.

Additional Resources:

It’s OK to Push Back

Sometimes reviewers make mistakes. It’s OK to push back on changes your reviewer requested. If you have a good reason for doing something a certain way, you are absolutely allowed to debate the merits of a requested change. Both the reviewer and reviewee should strive to discuss these issues in a polite and respectful manner.

You might be overruled, but you might also prevail. We’re pretty reasonable people.

Another phenomenon of open-source projects (where anyone can comment on any issue) is the dog-pile - your pull request gets so many comments from so many people it becomes hard to follow. In this situation, you can ask the primary reviewer (assignee) whether they want you to fork a new pull request to clear out all the comments. You don’t HAVE to fix every issue raised by every person who feels like commenting, but you should answer reasonable comments with an explanation.

Common Sense and Courtesy

No document can take the place of common sense and good taste. Use your best judgment, while you put a bit of thought into how your work can be made easier to review. If you do these things your pull requests will get merged with less friction.

Trivial Edits

Each incoming Pull Request needs to be reviewed, checked, and then merged.

While automation helps with this, each contribution also has an engineering cost. Therefore it is appreciated if you do NOT make trivial edits and fixes, but instead focus on giving the entire file a review.

If you find one grammatical or spelling error, it is likely there are more in that file, you can really make your Pull Request count by checking the formatting, checking for broken links, and fixing errors and then submitting all the fixes at once to that file.

Some questions to consider:

Can the file be improved further?
Does the trivial edit greatly improve the quality of the content?

Large or Automatic Edits

Some tools make it very easy to create large and/or automatic Pull Requests, for example:

global search/replace
linters which automatically correct issues (see also next section)
AI tools (large language models, assistants, etc) which generate code or documentation

To make it easier for reviewers to handle such Pull Requests, please explain how it was generated in the “Special notes for your reviewer” section of the Pull Request description. Reviewers may then be able to reproduce those steps (search/replace, linters) or can start the review with the right expectations (AI tools). Also consider the section about splitting up Pull Requests above.

Even with such tools it is still your responsibility as submitter of a Pull Request to ensure that the change is correct (to the best of your knowledge), and that making the change improves the project enough to justify the cost that is needed to review and merge the Pull Request (see previous section). If unsure, create a Draft Pull Request and ask for guidance.

Please understand that reviewers may decide to close a Pull Request with a reference to this documentation if they come to the conclusion that the difficulty of properly reviewing the Pull Request outweighs the benefit that the Pull Request provides.

AI Guidance

Using AI tools to help write your PR is acceptable, but as the author, you are responsible for understanding every change. Do not leave the first review of AI generated changes to the reviewers, verify the changes (code review, testing, etc.) before submitting your PR. Reviewers may ask questions about your AI-assisted code, and if you cannot explain why a change was made, the PR will be closed. When responding to review comments, please do so without relying on AI tools. Reviewers want to engage directly with you, not with generated responses. If you used AI tools in preparing your PR, please disclose this in the “Special notes for your reviewer” section. All contributions must follow the contributions policies and use commit messages that align with the policy. Large AI generated PRs and AI generated commit messages are discouraged.

Fixing Linter Issues

Kubernetes has a set of linter checks. Some of those must pass in the entire code base, some must pass in new or modified code, and some are merely hints to developers how to improve their code.

Please do not create Pull Requests for issues found by linters without first reaching out to maintainers on the #code-organization Slack channel to determine whether there is sufficient interest in fixing such issues.

When it was discussed, make sure to include people who gave the preliminary approval of this work as well as the link to the discussion on Slack or GitHub issue into the PR description. This is a good example to follow:

/area code-organization

This PR fixes linter rules discussed in the Slack https://kubernetes.slack.com/archives/Foo/Bar. Preliminary agreement to address those issues were given by @GHHandle1 and @GHHandle2.

/assign @GHHandle1 /assign @GHHandle2

This PR fixes issues in the package: pkg/kubelet

Related PRs for other packages:

github.com/link-to-other-PR1

github.com/link-to-other-PR2

It does not matter whether the linter is enabled in Kubernetes or not:

If a linter is enabled in golangci.yaml, then it has already been determined that sweeping changes in the existing code aren’t necessary or just are not worth the cost (e.g. causing rebases of other Pull Requests or obscuring authorship).
If a linter is not enabled, then it might not be important enough.
If the check is performed by third party tools which are not integrated in the Kubernetes CI or proprietary, file a bug or start a discussion about it first.

Such Pull Requests are often large and thus hard to review. When the linter enforces some opinion or policy, then this is not necessarily something that applies to Kubernetes. Kubernetes uses the formatting rules enforced by Go. Stricter rules like specific usage of whitespace or using standard library constants are opinionated and not worth the cost of introducing them now.

Linters worth considering are those which actually improve code correctness, for example by warning about suspicious code like calling a function and then not checking the error result.

The Testing and Merge Workflow

The Kubernetes merge workflow uses labels, applied by commands via comments. These will trigger actions on your pull request. Different Kubernetes repositories may require different labels on the path to approval. A generic explanation of how labels are used in pull requests can be found here. The pull request bot will also automatically apply and/or suggest labels.

Example: To apply a SIG label, you would type in a comment:

/sig apps

NOTE: For pull requests that are in progress but not ready for review, prefix the pull request title with WIP or [WIP] and track any remaining TODOs in a checklist in the pull request description.

Here’s the process the pull request goes through on its way from submission to merging:

Make the pull request
@k8s-ci-robot assigns reviewers
If you’re not a member of the Kubernetes organization, a Reviewer/Kubernetes Member checks that the pull request is safe to test. If so, they comment /ok-to-test. Pull requests by Kubernetes organization members do not need this step. Now the pull request is considered to be trusted, and the pre-submit tests will run:
1. Automatic tests run. See the current list of tests at this link
2. If tests fail, resolve issues by pushing edits to your pull request branch
3. If the failure is a flake, anyone on trusted pull requests can comment /retest to rerun failed tests
Reviewer suggests edits
Push edits to your pull request branch
Repeat the prior two steps as needed until the reviewer(s) add /lgtm label. The /lgtm label, when applied by someone listed as a reviewer in the corresponding project OWNERS file, is a signal that the code has passed review from one or more trusted reviewers for that project
(Optional) Some reviewers prefer that you squash commits at this step
Follow the bot suggestions to assign an OWNER who will add the /approve label to the pull request. The /approve label, when applied by someone listed as an approver in the corresponding project OWNERS, is a signal that the code has passed final review and is ready to be automatically merged

The behavior of Prow is configurable across projects. You should be aware of the following configurable behaviors.

If you are listed as an /approver in the OWNERS file, an implicit /approve can be applied to your pull request. This can result in a merge being triggered by a /lgtm label. This is the configured behavior in many projects, including kubernetes/kubernetes. You can remove the implicit /approve with /approve cancel
/lgtm can be configured so that from someone listed as both a reviewer and an approver will cause both labels to be applied. For kubernetes/kubernetes and many other projects this is not the default behavior, and /lgtm is decoupled from /approve

Once the tests pass, and the reviewer adds the lgtm and approved labels, the pull request enters the final merge pool. The merge pool is needed to make sure no incompatible changes have been introduced by other pull requests since the tests were last run on your pull request.

Tide will manage the merge pool automatically. It uses GitHub queries to select PRs into “tide pools”, runs as many in a batch as it can (“tide comes in”), and merges them (“tide goes out”).

The pull request enters the merge pool if the merge criteria are met. The PR dashboard shows the difference between your PR’s state and the merge criteria so that you can easily see all criteria that are not being met and address them.
If tests fail, resolve issues by pushing edits to your pull request branch
If the failure is a flake, anyone can comment /retest if the pull request is trusted
If tests pass, Tide automatically merges the pull request

That’s the last step. Your pull request is now merged.

More About `Ok-To-Test`

The ok-to-test label is applied by org members to PRs from external contributors, it signals that the PR can be tested.
For a Contributor, an ok-to-test label means the regular CI tests will be run for their PR.
For the reviewer or the member, labelling the PR with ok-to-test it means a lot more:
- They need to take care if the PR is not a wastage of our CI/CD resources.
- Is the PR worth testing or does it need more changes before going through the CI/CD process?
- Is the PR getting used to run malicious code to misuse our resources ?
An ok-to-test label may reduce the workload and smoothens the contributors experience as they can know if there is any failing test. If there is, you can fix the test and they don’t have to wait for a long time to get a review from maintainer/assignee.
There are various other factors on which labelling of ok-to-test depends :
- Size of PR :
  - If the PR is of size/S or size/M which is just to fix a grammatical error or spelling mistake, the reviewer can trigger the CI/CD without having a second thought.
  - If the PR is of size/XXL which aims at adding a new feature, a new API endpoint or any new substantial feature. There needs to other conventions & process to be followed regarding the change made. Hence, it may have a slight delay to get labelled with ok-to-test.
- Other org members who are not assigned to the following PR may also label ok-to-test , if the change is small.
- If the PR is labelled with cncf-cla: no, then it is better to wait before labelling ok-to-test.
- PRs with tag do-not-merge/hold or needs-rebase should make the appropriate changes before the PR can be labelled ok-to-test.
- PRs created by mistake without to meaningful change of code should not be labelled ok-to-test and closed.

Docs: GitHub Workflow

Mon, 01 Jan 0001 00:00:00 +0000

1. Fork in the cloud

Visit https://github.com/kubernetes/kubernetes
Click Fork button (top right) to establish a cloud-based fork.

2. Clone fork to local storage

In your shell, define a local working directory as working_dir.

export working_dir="${HOME}/src/k8s.io" # Change to your preferred location for source code

Set user to match your github profile name:

export user=<your github profile name>

Both $working_dir and $user are mentioned in the figure above.

Create your clone:

mkdir -p $working_dir
cd $working_dir
git clone https://github.com/$user/kubernetes.git
# or: git clone git@github.com:$user/kubernetes.git

cd $working_dir/kubernetes
git remote add upstream https://github.com/kubernetes/kubernetes.git
# or: git remote add upstream git@github.com:kubernetes/kubernetes.git

# Never push to upstream master
git remote set-url --push upstream no_push

# Confirm that your remotes make sense:
git remote -v

3. Create a Working Branch

Get your local master up to date. Note that depending on which repository you are working from, the default branch may be called “main” instead of “master”.

cd $working_dir/kubernetes
git fetch upstream
git checkout master
git rebase upstream/master

Create your new branch.

git checkout -b myfeature

You may now edit files on the myfeature branch.

Building Kubernetes

This workflow is process-specific. For quick-start build instructions for kubernetes/kubernetes, please see here.

4. Keep your branch in sync

You will need to periodically fetch changes from the upstream repository to keep your working branch in sync. Note that depending on which repository you are working from, the default branch may be called ‘main’ instead of ‘master’.

Make sure your local repository is on your working branch and run the following commands to keep it in sync:

git fetch upstream
git rebase upstream/master

Please don’t use git pull instead of the above fetch and rebase. Since git pull executes a merge, it creates merge commits. These make the commit history messy and violate the principle that commits ought to be individually understandable and useful (see below).

You might also consider changing your .git/config file via git config branch.autoSetupRebase always to change the behavior of git pull, or another non-merge option such as git pull --rebase.

5. Commit Your Changes

You will probably want to regularly commit your changes. It is likely that you will go back and edit, build, and test multiple times. After a few cycles of this, you might amend your previous commit.

git commit

6. Push to GitHub

When your changes are ready for review, push your working branch to your fork on GitHub.

git push -f <your_remote_name> myfeature

7. Create a Pull Request

Visit your fork at https://github.com/<user>/kubernetes
Click the Compare & Pull Request button next to your myfeature branch.
Check out the pull request process for more details and advice.

If you have upstream write access, please refrain from using the GitHub UI for creating PRs, because GitHub will create the PR branch inside the main repository rather than inside your fork.

Get a code review

Once your pull request has been opened it will be assigned to one or more reviewers. Those reviewers will do a thorough code review, looking for correctness, bugs, opportunities for improvement, documentation and comments, and style.

Commit changes made in response to review comments to the same branch on your fork.

Very small PRs are easy to review. Very large PRs are very difficult to review.

Squash commits

After a review, prepare your PR for merging by squashing your commits.

All commits left on your branch after a review should represent meaningful milestones or units of work. Use commits to add clarity to the development and review process.

Before merging a PR, squash the following kinds of commits:

Fixes/review feedback
Typos
Merges and rebases
Work in progress

Aim to have every commit in a PR compile and pass tests independently if you can, but it’s not a requirement. In particular, merge commits must be removed, as they will not pass tests.

To squash your commits, perform an interactive rebase:

Check your git branch:

git status

The output should be similar to this:

On branch your-contribution
Your branch is up to date with 'origin/your-contribution'.

Start an interactive rebase using a specific commit hash, or count backwards from your last commit using HEAD~<n>, where <n> represents the number of commits to include in the rebase.

git rebase -i HEAD~3

The output should be similar to this:

pick 2ebe926 Original commit
pick 31f33e9 Address feedback
pick b0315fe Second unit of work
# Rebase 7c34fc9..b0315ff onto 7c34fc9 (3 commands)
#
# Commands:
# p, pick <commit> = use commit
# r, reword <commit> = use commit, but edit the commit message
# e, edit <commit> = use commit, but stop for amending
# s, squash <commit> = use commit, but meld into previous commit
# f, fixup <commit> = like "squash", but discard this commit's log message
...

Use a command line text editor to change the word pick to squash for the commits you want to squash, then save your changes and continue the rebase:

pick 2ebe926 Original commit
squash 31f33e9 Address feedback
pick b0315fe Second unit of work
...

The output after saving changes should look similar to this:

[detached HEAD 61fdded] Second unit of work
Date: Thu Mar 5 19:01:32 2020 +0100
2 files changed, 15 insertions(+), 1 deletion(-)
...
Successfully rebased and updated refs/heads/master.

Force push your changes to your remote branch:

git push --force-with-lease

For mass automated fixups such as automated doc formatting, use one or more commits for the changes to tooling and a final commit to apply the fixup en masse. This makes reviews easier.

An alternative to this manual squashing process is to use the Prow and Tide based automation that is configured in GitHub: adding a comment to your PR with /label tide/merge-method-squash will trigger the automation so that GitHub squash your commits onto the target branch once the PR is approved. Using this approach simplifies things for those less familiar with Git, but there are situations in where it’s better to squash locally; reviewers will have this in mind and can ask for manual squashing to be done.

By squashing locally, you control the commit message(s) for your work, and can separate a large PR into logically separate changes. For example: you have a pull request that is code complete and has 24 commits. You rebase this against the same merge base, simplifying the change to two commits. Each of those two commits represents a single logical change and each commit message summarizes what changes. Reviewers see that the set of changes are now understandable, and approve your PR.

Merging a commit

Once you’ve received review and approval, your commits are squashed, your PR is ready for merging.

Merging happens automatically after both a Reviewer and Approver have approved the PR. If you haven’t squashed your commits, they may ask you to do so before approving a PR.

Reverting a commit

In case you wish to revert a commit, use the following instructions.

If you have upstream write access, please refrain from using the Revert button in the GitHub UI for creating the PR, because GitHub will create the PR branch inside the main repository rather than inside your fork.

Create a branch and sync it with upstream. Note that depending on which repository you are working from, the default branch may be called ‘main’ instead of ‘master’.
```
# create a branch
git checkout -b myrevert

# sync the branch with upstream
git fetch upstream
git rebase upstream/master
```

If the commit you wish to revert is a merge commit, use this command:

# SHA is the hash of the merge commit you wish to revert
git revert -m 1 <SHA>

If it is a single commit, use this command:

# SHA is the hash of the single commit you wish to revert
git revert <SHA>

This will create a new commit reverting the changes. Push this new commit to your remote.
```
git push <your_remote_name> myrevert
```
Finally, create a Pull Request using this branch.

Docs: Coding Conventions

Mon, 01 Jan 0001 00:00:00 +0000

Code conventions

Bash
- Shell Style Guide
- Ensure that build, release, test, and cluster-management scripts run on macOS
Go
- Go Code Review Comments
- Effective Go
- Know and avoid Go landmines
- Comment your code.
  - Go’s commenting conventions
  - If reviewers ask questions about why the code is the way it is, that’s a sign that comments might be helpful.
- Command-line flags should use dashes, not underscores
- Naming
  - Please consider package name when selecting an interface name, and avoid redundancy. For example, storage.Interface is better than storage.StorageInterface.
  - Do not use uppercase characters, underscores, or dashes in package names.
  - Please consider parent directory name when choosing a package name. For example, pkg/controllers/autoscaler/foo.go should say package autoscaler not package autoscalercontroller.
    - Unless there’s a good reason, the package foo line should match the name of the directory in which the .go file exists.
    - Importers can use a different name if they need to disambiguate.
  - Locks should be called lock and should never be embedded (always lock sync.Mutex). When multiple locks are present, give each lock a distinct name following Go conventions: stateLock, mapLock etc.
- API changes
- API conventions
- Kubectl conventions
- Logging conventions

Testing conventions

All new packages and most new significant functionality must come with unit tests.
Table-driven tests are preferred for testing multiple scenarios/inputs. For an example, see TestNamespaceAuthorization.
Significant features should come with integration (test/integration) and/or end-to-end (test/e2e) tests.
- Including new kubectl commands and major features of existing commands.
Unit tests must pass on macOS and Windows platforms - if you use Linux specific features, your test case must either be skipped on windows or compiled out (skipped is better when running Linux specific commands, compiled out is required when your code does not compile on Windows).
Avoid relying on Docker Hub. Use the Google Cloud Artifact Registry instead.
Do not expect an asynchronous thing to happen immediately—do not wait for one second and expect a pod to be running. Wait and retry instead.
See the testing guide for additional testing advice.

Directory and file conventions

Avoid package sprawl. Find an appropriate subdirectory for new packages. See issue #4851 for discussion.
- Libraries with no appropriate home belong in new package subdirectories of pkg/util.
Avoid general utility packages. Packages called “util” are suspect. Instead, derive a name that describes your desired function. For example, the utility functions dealing with waiting for operations are in the wait package and include functionality like Poll. The full name is wait.Poll.
All filenames should be lowercase.
Go source files and directories use underscores, not dashes.
- Package directories should generally avoid using separators as much as possible. When package names are multiple words, they usually should be in nested subdirectories.
Document directories and filenames should use dashes rather than underscores.
Examples should also illustrate best practices for configuration and using the system.
Follow these conventions for third-party code:
- Go code for normal third-party dependencies is managed using go modules and is described in the kubernetes vendoring guide.
- Other third-party code belongs in third_party.
  - forked third party Go code goes in third_party/forked.
  - forked golang stdlib code goes in third_party/forked/golang.
- Third-party code must include licenses. This includes modified third-party code and excerpts, as well.

Docs: Help Wanted and Good First Issue Labels

Mon, 01 Jan 0001 00:00:00 +0000

Overview

We use two labels to identify issues that have been specifically created or selected for new contributors: help wanted and good first issue. The good first issue label is a subset of the help wanted label, indicating that members have committed to providing extra assistance for new contributors. All good first issue items also have the help wanted label.

We also have some suggestions for using these labels to help grow and improve our community.

Help Wanted

Items marked with the help wanted label need to ensure that they meet these criteria:

Clear Task The task is agreed upon and does not require further discussions in the community. Call out if that area of code is untested and requires new fixtures. Consensus should exist for the high-level approach.

API and CLI behavior should be decided and included in the OP issue, for example: “The new command syntax is svcat unbind NAME [--orphan] [--timeout 5m]”, with expected validations called out.
Goldilocks priority The priority should not be so high that a core contributor should do it, but not too low that it isn’t useful enough for a core contributor to spend time reviewing it, answering questions, helping get it into a release, etc.
Up-To-Date Often these issues become obsolete and have already been completed, are no longer desired, no longer make sense, or have changed priority or difficulty.

A good example of a Help Wanted issue description can be found here: kubernetes/test-infra#21356 (comment).

These commands can be used with GitHub issues to manage the help wanted label:

/help : Adds the help wanted label to an issue.
/remove-help : Removes the help wanted label from an issue. If the good first issue label is present, it is removed as well.

Good First Issue

Items marked with the good first issue label are intended for first-time contributors. It indicates that members will keep an eye out for these pull requests and shepherd it through our processes.

New contributors should not be left to find an approver, ping for reviews, decipher prow commands, or identify that their build failed due to a flake. It is important to make new contributors feel welcome and valued. We should assure them that they will have an extra level of help with their first contribution.

After a contributor has successfully completed one or two good first issue items, they should be ready to move on to help wanted items.

All good first issue items need to follow the guidelines for help wanted items in addition to meeting the following criteria:

No Barrier to Entry The task is something that a new contributor can tackle without advanced setup or domain knowledge.
Solution Explained The recommended solution is clearly described in the issue.
Provides Context If background knowledge is required, this should be explicitly mentioned and a list of suggested readings included.
Gives Examples Link to examples of similar implementations so new contributors have a reference guide for their changes.
Identifies Relevant Code The relevant code and tests to be changed should be linked in the issue.
Ready to Test There should be existing tests that can be modified, or existing test cases fit to be copied. If the area of code doesn’t have tests, before labeling the issue, add a test fixture. This prep often makes a great help wanted task!

A good example of a good first issue description can be found here: kubernetes/kubernetes#68231.

These commands can be used in the GitHub issue comments to control the good first issue label:

/good-first-issue : Adds the good first issue label to an issue. Also adds the help wanted label, if not already present.
/remove-good-first-issue : Removes the good first issue label from an issue.

Suggestions for Experienced Community Members

We encourage our more experienced members to help new contributors, so that the Kubernetes community can continue to grow and maintain the kind, inclusive community that we all enjoy today.

The following suggestions go a long way toward preventing “drive-by” PRs, and ensure that our investment in new contributors is rewarded by returning contributors.

Provide extra assistance during reviews on good first issue pull requests.
Answer questions and identify useful docs.
Offer advice such as “One way to reproduce this in a cluster is to do X and then you can use kubectl to poke around,” or “Did you know that you can use fake clients to setup and test this easier?”
Help new contributors learn enough about the project, setting up their environment, running tests, and navigating this area of the code so that they can tackle a related help wanted issue next time.

If you make someone feel like a part of our community, they will know that it is safe to ask questions, that people will let them know the rules, and that their contributions are helpful and appreciated. They will stick around! 🌈

Encourage new contributors to seek help on the appropriate slack channels, introduce them, and include them in your conversations.
Invite them to the SIG meetings.
Give credit to new contributors so that others get to know them: “Hey, would someone help give a second LGTM on @newperson’s first PR on chocolate bunnies?” Mention them in the SIG channel and meeting, and thank them on Twitter or #shoutouts.
Use all the emoji in your approve or lgtm comment. 💖 🚀
Let them know that their good first issue is getting extra attention to make the first one easier and help them find a follow-up issue.
Suggest a related help wanted so that can build up experience in an area.
People are more likely to continue contributing when they know what to expect. They want to know the acceptable way to ask for people to review a PR, and how to nudge things along when a PR is stalled. Show them how we operate by helping move their first PR along.
If you have time, let the contributor know that they can DM you with questions that they aren’t yet comfortable asking the wider group.

Docs: Issue Triage Guidelines

Mon, 01 Jan 0001 00:00:00 +0000

Scope

These guidelines serve as a primary document for triaging incoming issues to Kubernetes. SIGs and projects are encouraged to use this guidance as a starting point, and customize to address specific triaging needs.

Note: These guidelines only apply to the Kubernetes repository. Usage for other Kubernetes-related GitHub repositories is TBD.

What Is Triaging?

Issue triage is a process by which a SIG intakes and reviews new GitHub issues and requests, and organizes them to be actioned—either by its own members, or by other SIGs. Triaging involves categorizing issues and pull requests based on factors such as priority/urgency, SIG ownership of the issue, and the issue kind (bug, feature, etc.).

Triage can happen asynchronously and continuously, or in regularly scheduled meetings. Several Kubernetes SIGs and projects have adopted their own approaches to triaging.

Why Is Triaging Beneficial?

SIGs who triage regularly say it offers a number of benefits, such as:

Speeding up issue management
Keeping contributors engaged by shortening response times
Preventing work from lingering endlessly
Replacing special requests and one-offs with a neutral process that acts like a boundary
Greater transparency, interesting discussions, and more collaborative, informed decision-making
Building prioritization, negotiation and decision-making skills, which are critical to most tech roles
Reinforcement of SIG community and culture

People who enjoy product management and iterating on processes tend to enjoy triaging because it empowers their SIGs to maintain a steady, continuous flow of work that is assessed and prioritized based on feedback and value.

How to Triage: A Step-by-Step Flow

This guide walks you through a standard triaging process, beginning with tools and tips.

These are tools that your SIG can use to make the triage process simpler, more efficient and faster.

Permissions and the Bot

Opening new issues and leaving comments on other people’s issues are possible for all contributors. However, permission to assign specific labels (such as triage), change milestones, or close other contributors issues is only granted to the author of an issue, assignees, and organization members. For this reason, we use a bot to manage labelling and triaging. For a full list of the bot’s commands and permissions, see the Prow command reference page.

Triage Party

Triage Party is a tool for triaging incoming GitHub issues for large open-source projects, built with the GitHub API. Made public in April 2020, it facilitates “massively multi-player GitHub triage” and reduces contributor response latency.

Its features include:

Queries across multiple repositories
Queries that are not possible on GitHub:
- conversation direction (tag: recv, tag: send)
- duration (updated: +30d)
- regexp (label: priority/.*)
- reactions (reactions: >=5)
- comment popularity (comments-per-month: >0.9)
Multiplayer mode: for simultaneous group triage of a pool of issues
Button to open issue groups as browser tabs (pop-ups must be disabled)
“Shift-Reload” for live data pull

GitHub Project Boards

GitHub offers project boards, set up like kanban boards, to help teams organize and track their workflow in order to get work done. The Release Team has come to depend on their project board for planning new Kubernetes releases; they also use it as an archive to show the work done for past releases.

Other SIGs are also using project boards:

We encourage more SIGs to use project boards to enhance visibility and tracking. If you’d like some help getting started, visit GitHub’s documentation or reach out to SIG Contributor Experience.

DevStats

The CNCF has created a suite of Grafana dashboards and charts for collecting metrics related to all the CNCF projects. The Kubernetes dashboard can be used to help SIGs view real-time metrics on many aspects of their workflow, including:

Issue Velocity: How quickly issues are resolved
PR Velocity: Including PR workload per SIG, PR time to approve and merge, and other data

Process Pointers and Advice from SIGs

Several SIGs consistently meet weekly or monthly to triage issues. Here are some details about their processes.

Running a Triage Meeting: Tips from api-machinery

The api-machinery SIG has found that triage meetings offer valuable opportunities for newcomers to listen, learn, and start contributing. The SIG hold triage meetings every Tuesday and Thursday and archive recordings via their YouTube playlist. Watch an example of one of their meetings.

In a typical triage meeting, api-machinery members sort through every issue that they haven’t triaged since the previous meeting, using a simple query and issue number to track open PRs and issues. They usually follow this process:

Read through the comments and the code briefly to understand what the issue is about.
Determine by consensus if it belongs to the api-machinery SIG or not. If not, remove the sig/api-machinery label.
Label other SIGs, if appropriate
Discuss briefly the technical implications
Assign people with expertise in the domain to review, comment, reject, etc.

The api-machinery SIG has found that consistently meeting on a regular, fixed schedule is key to the success of a triaging effort. More frequent, small meetings are better than infrequent, large meetings. They also offer a few other pointers for successful triage meetings:

We try to balance the load, and ask people if they are okay taking on an issue before assigning it to them.
We skip issues that are closed.
We also skip cherrypicks, because we consider that the code change was reviewed in the original PR.
We ensure participation from the entire SIG and support company diversity.
We use this opportunity to add help wanted and good first issue labels.

Triage Guide by cluster-lifecycle

The cluster-lifecycle SIG has developed a triaging page detailing their process, including the Milestones stage. Here is a March 2020 presentation delivered to the SIG chairs and leads group on their process.

Step One: Review Newly Created Open Issues

The first step in a successful triage meeting is reviewing newly created open issues. Kubernetes issues are listed here. Labels are the primary tools for triaging. Here’s a comprehensive label list.

New issues are automatically assigned a needs-triage label indicating that these issues are currently awaiting triage. After triaging an issue, the issue owning SIG will use the bot command /triage accepted. This command removes the needs-triage label and adds the triage/accepted label.

Note that adding labels requires Kubernetes GitHub org membership. If you are not an org member, you should add your triage findings as a comment.

Conducting Searches

GitHub allows you to filter out types of issues and pull requests, which helps you discover items in need of triaging. This table includes some predetermined searches for convenience:

Search	What it sorts
created-asc	Untriaged issues by age
needs-sig	Issues that need to be assigned to a SIG
`is:open is:issue`	Newest incoming issues
comments-desc	Busiest untriaged issues, sorted by # of comments
comments-asc	Issues that need more attention, based on # of comments

We suggest preparing your triage by filtering out the oldest, unlabelled issues and pull requests first.

Step Two: Triage Issues by Type

Use these triage/ and kind/support labels to find open issues that can be quickly closed. A triage engineer can add the appropriate labels.

Depending on your permissions, either close or comment on any issues that are identified as support requests, duplicates, or not-reproducible bugs, or that lack enough information from the reporter.

Support Requests

Some people mistakenly use GitHub issues to file support requests. Usually they are asking for help configuring some aspect of Kubernetes. To handle such an issue, direct the author to use our support request channels. Then apply the kind/support label, which is directed to our support structures, and apply the close label.

Please find more detailed information about Support Requests in the Further Notes section.

Abandoned or Wrongly Placed Issues

If an issue is abandoned or in the wrong place, either close or comment on it.

Needs More Information

The triage/needs-information label indicates an issue needs more information in order for work to continue; comment on or close it.

Bugs

First, validate if the problem is a bug by trying to reproduce it.

If you can reproduce it:

Define its priority.
Search for duplicates to see if the issue has been reported already. If a duplicate is found, let the issue reporter know, reference the original issue, and close the duplicate.

If you can’t reproduce it:

Contact the issue reporter with your findings .
Close the issue if both the parties agree that it could not be reproduced.

If you need more information to further work on the issue:

Let the reporter know it by adding an issue comment. Include /triage needs-information in the comment to apply the triage/needs-information label.

In all cases, if you do not get a response within 20 days, close the issue with an appropriate comment. If you have permission to close someone else’s issue, first /assign the issue to yourself, then /close it. If you do not, please leave a comment describing your findings.

Help Wanted/Good First Issues

To identify issues that are specifically groomed for new contributors, we use the help wanted and good first issue labels. To use these labels:

Review our specific guidelines for how to use them.
If the issue satisfies these guidelines, you can add the help wanted label with the /help command. and the good first issue label with the /good-first-issue command. Please note that adding the good first issue label will also automatically add the help wanted label.
If an issue has these labels but does not satisfy the guidelines, please ask for more details to be added to the issue or remove the labels using the /remove-help or /remove-good-first-issue commands.

Kind Labels

Usually the kind label is applied by the person submitting the issue. Issues that feature the wrong kind (for example, support requests labelled as bugs) can be corrected by someone triaging; double-checking is a good approach. Our issue templates aim to steer people to the right kind.

Step Three: Define Priority

We use GitHub labels for prioritization. If an issue lacks a priority label, this means it has not been reviewed and prioritized yet.

We aim for consistency across the entire project. However, if you notice an issue that you believe to be incorrectly prioritized, please leave a comment offering your counter-proposal and we will evaluate it.

Priority label	What it means	Examples
`priority/critical-urgent`	Team leaders are responsible for making sure that these issues (in their area) are being actively worked on—i.e., drop what you’re doing. Stuff is burning. These should be fixed before the next release.	user-visible bugs in core features broken builds tests and critical security issues
`priority/important-soon`	Must be staffed and worked on either currently or very soon—ideally in time for the next release. Important, but wouldn’t block a release.	[XXXX]
`priority/important-longterm`	Important over the long term, but may not be currently staffed and/or may require multiple releases to complete. Wouldn’t block a release.	[XXXX]
`priority/backlog`	General agreement that this is a nice-to-have, but no one’s available to work on it anytime soon. Community contributions would be most welcome in the meantime, though it might take a while to get them reviewed if reviewers are fully occupied with higher-priority issues—for example, immediately before a release.	[XXXX]
`priority/awaiting-more-evidence`	Possibly useful, but not yet enough support to actually get it done.	Mostly placeholders for potentially good ideas, so that they don’t get completely forgotten, and can be referenced or deduped every time they come up

Step Four: Find and Set the Right SIG(s) to Own an Issue

Components are divided among Special Interest Groups (SIGs). The bot assists in finding a proper SIG to own an issue.

For example, typing /sig network in a comment should add the sig/network label.
Multiword SIGs use dashes: for example, /sig cluster-lifecycle.
Keep in mind that these commands must be on their own lines, and at the front of the comment.
If you are not sure about who should own an issue, defer to the SIG label only.
If you feel an issue should warrant a notification, ping a team with an @ mention, in this format: @kubernetes/sig-<group-name>-<group-suffix>. Here, the <group-suffix> can be one of:
- bugs
- feature-requests
- pr-reviews
- test-failures
- proposals For example: @kubernetes/sig-cluster-lifecycle-bugs, can you have a look at this?

Self-Assigning

If you think you can fix the issue, assign it to yourself with just the /assign command. If you cannot self-assign for permissions-related reasons, leave a comment that you’d like to claim it and begin working on a PR.

When an issue already has an assignee, do not assign it to yourself or create a PR without talking to the existing assignee or going through the Follow Up steps as described in this document. Creating a PR when someone else is already working on an issue is not a good practice and is discouraged.

Step Five: Follow Up

If No PR is Created for an Issue Within the Current Release Cycle

If an issue is owned by a developer but a PR has not been created within 30 days, a triage engineer should contact the issue owner and ask them to either create a PR or release ownership.

If a SIG Label Is Assigned, but No Action Is Taken Within 30 Days

If you find an issue with a SIG label assigned, but there’s no evidence of movement or discussion within 30 days, then gently poke the SIG about this pending issue. Also, consider attending one of their meetings to bring up the issue.

If an Issue Has No Activity After 90 Days

When an issue goes 90 days without activity, the k8s-triage-robot adds the lifecycle/stale label to that issue. You can block the bot by applying the /lifecycle frozen label preemptively, or remove the label with the /remove-lifecycle stale command. The k8s-triage-robot adds comments in the issue that include additional details. If you take neither step, the issue will eventually be auto-closed.

Further Notes

Support Requests: Channels

These should be directed to the following:

User Support Response: Example

If you see support questions on dev@kubernetes.io or issues asking for support, try to redirect them to Discuss. Here is an example response:

Please re-post your question to our Discussion Forums.

We are trying to consolidate the channels to which questions for help/support are posted so that we can improve our efficiency in responding to your requests, and to make it easier for you to find answers to frequently asked questions and how to address common use cases.

We regularly see messages posted in multiple forums, with the full response thread only in one place or, worse, spread across multiple forums. Also, the large volume of support issues on GitHub is making it difficult for us to use issues to identify real bugs.

Members of the Kubernetes community use Discussion Forums to field support requests. Before posting a new question, please search these for answers to similar questions, and also familiarize yourself with:

user documentation

troubleshooting guide

Again, thanks for using Kubernetes.

The Kubernetes Team

Docs: Non-code Contributions

Mon, 01 Jan 0001 00:00:00 +0000

This section is new and in progress. Expect this document to change often.

If you are interested in helping define and structure this work, check the weekly meeting notes for information on how to get involved. You can also find us in the SIG Contributor Experience Slack channel.

All contributors welcome, new and old!

What is this?

The list below is meant to help non-code contributors find areas of the Kubernetes project where their expertise can be best utilized. The goal of this is to both provide a starting guide for anyone looking to become a contributor not necessarily writing code, and also to fill any needs that the SIGs have that might not currently be filled by code-focused contributors.

This list is meant to be used by both new contributors looking for a good entrance into the project, and current contributors who would like to do something different.

Are you interested in any of the roles below? Come chat with us on Slack!

Project general roles

These are roles that either span the project as a whole, or span several areas of the project. Most of the roles below can be considered “good-first-roles”.

Community education
- Answering questions on Discuss, Slack, StackOverflow, etc
  - Slack
  - YouTube
- Onboarding new contributors
  - Capturing the experiences of “Fresh Eyes” in the project
- Getting more people to SIG-Docs
  - Contribute to Kubernetes docs
- Doing demos
  - Kubernetes Weekly Community Meeting
    - YouTube
Outward facing community work (might be more CNCF-oriented)
- Hosting meetups and general evangelism
- Presentation of work to meetups
- Visual Communication
  - Diagrams and visual explanations of concepts
  - Infographic design
  - Icon design
  - Various artistic contributions to strengthen kubernetes brand, evangelize the project, and develop community
Non-Documentation writing
- Blogging about early experiences
- Operational manuals
  - Walkthroughs
  - How-tos about integration experiences, tools, etc
  - Playbooks for Ansible, Chef, Salt, etc
- Indexing of blogs, videos, etc
- Maintaining content for the new Contributor Site
Management of communication tools (at the discretion of project maintainers)
- Mailing list moderation
- Slack or Discourse management
- Calendar management
- Analysis of our comm tools/metrics
Volunteer management
- Finding/Funneling contributors to the right SIGs or WGs
- Recognition of those who contribute a lot
- Recognition of projects and growth efforts
Issue Triage
- Issue triage & labeling
Event management
- Helping run Contributor Summits
- Co-organizing Meetups
- Staffing Kubernetes booths at conferences

SIG-specific roles

These are roles that are important to each and every SIG within the Kubernetes project. If you are interested in a specific topic within the project, you can contribute in several different ways for that specific SIG.

Documentation
- Common documentation for the SIG expertise area
- Updates
  - Reviewing/logging technical ownership for documentation that might need updating
- Translation
UX/UI Design
Release team roles
- All roles have shadows for onboarding new members
Project management
- Confirming ownership of tasks, issues, objects, etc
  - Rectifying “owned by everyone, so owned by no-one”
Pull requests
- PR triage & labeling
- Editing PR text: release note, statement
Events
- Organizing/helping run Face-to-Face meetings for SIGs/WGs/subprojects
- Putting together SIG Intros & Deep-dives for KubeCon/CloudNativeCon
Managing & Uploading Recordings to YouTube

Non-Code Tasks in Primarily-Code roles

These are roles that are not code-based, but require knowledge of either general coding, or specific domain knowledge of the Kubernetes code base.

Documentation
- Documenting new features
Some release roles
- Managing release notes
Github management (Tags, repos, etc)

Post-Code Roles

These are roles that are not code-based, but require knowledge of either general coding, or specific domain knowledge of the Kubernetes code base.

Technical project leadership
- Specifically, SIG-Architecture and Steering Committee
Some release roles
- Release Lead, Features Lead, etc
Mentoring new contributors

Docs: Adding Release Notes

Mon, 01 Jan 0001 00:00:00 +0000

On the kubernetes/kubernetes repository, release notes are required for any pull request with user-visible changes, this could mean:

User facing, critical bug-fixes
Notable feature additions
Output format changes
Deprecations or removals
Metrics changes
Dependency changes
API changes

Release notes are one of the most important reference points for users about to install or upgrade to a particular release of Kubernetes.

Does my pull request need a release note?

Any user-visible or operator-visible change qualifies for a release note. This could be a:

CLI change
API change
UI change
configuration schema change
behavioral change
change in non-functional attributes such as efficiency or availability, availability of a new platform
a warning about a deprecation
fix of a previous Known Issue
fix of a vulnerability (CVE)

No release notes are required for changes to the following:

Tests
Build infrastructure
Fixes for unreleased bugs

Contents of a Release Note

A release note needs a clear, concise description of the change. This includes:

An indicator if the pull request Added, Changed, Fixed, Removed, Deprecated functionality or changed enhancement/feature maturity (alpha, beta, stable/GA)
An indicator if there is user Action required
The name of the affected API or configuration fields, CLI commands/flags or enhancement/feature
A link to relevant user documentation about the enhancement/feature

Writing Good Release Notes

Good release notes can make a huge difference to the end user. To make sure that your release notes are of the highest possible quality, follow these guidelines.

Write your release notes in the past tense. For example, use “Added” instead of “Add”, “Fixed” instead of “Fix”, and “Updated” instead of “Update”.
Include a call to action if there is anything the end user needs to do, along with a link to a blog post or documentation item to provide better context.
Keep your release notes relevant to the end user.
Use Markdown to add links and emphasis, to make your release notes more readable and usable.
Use good grammar and make sure you capitalize the first word of each sentence.

Here are some pull requests with examples of exemplary release notes:

For more tips on writing good release notes, check out the Release Notes Handbook.

Applying a Release Note

On the kubernetes/kubernetes repository, release notes are required for any pull request with user-visible changes.

To meet this requirement, do one of the following:

Add notes in the release notes block, or
Update the release note label

If you don’t add release notes in the pull request template, the do-not-merge/release-note-label-needed label is added to your pull request automatically after you create it. There are a few ways to update it.

To add a release-note section to the pull request description, add your release note beneath the question Does this PR introduce a user-facing change?

For pull requests that require additional action from users switching to the new release, include the string “action required” (case insensitive) in the release note.

For an example, see this pull request.

For pull requests that don’t need to be mentioned at release time, use the /release-note-none Prow command to add the release-note-none label to the PR. You can also write the string “NONE” as a release note in your PR description.

For an example of a pull request without release notes, take a look at this pull request.

Your release note should be written in clear and straightforward sentences. Most often, users aren’t familiar with the technical details of your PR, so consider what they need to know when you write your release note.

Some brief examples of release notes:

The deprecated flag --conntrack-max has been removed from kube-proxy. Users of this flag should switch to --conntrack-min and --conntrack-max-per-core instead. (#78399, @rikatz)
The --export flag for the kubectl get command, deprecated since v1.14, will be removed in v1.18.
Fixed a bug that prevents dry-run from being honored for the pod/eviction sub-resource. (#76969, @apelisse)

Pull Request titles and body comments can be modified at any time prior to the release to make them friendly for release notes.

The release notes team maintains a template for Kubernetes Release notes that may help clarify whether or not your PR requires a release note. The most recent Kubernetes Release notes can also provide insight into the writing style for release notes.

Release notes apply to pull requests on the master branch. For patch release branches the automated cherry-pick pull requests process (see the cherry-pick instructions) should be followed. That automation will pull release notes from the master branch PR from which the cherry-pick originated. On a rare occasion a pull request on a patch release branch is not a cherry-pick, but rather is targeted directly to the non-master branch and in this case, a release-note-* label is required for that non-master pull request.

Reviewing Release Notes

Reviewing the release notes of a pull request should be a dedicated step in the overall review process. It is necessary to rely on the same metrics as other reviewers to be able to distinguish release notes which might need to be rephrased.

As a guideline, a release notes entry needs to be rephrased if one of the following cases apply:

The release note does not communicate the full purpose of the change.
The release note has no impact on any user.
The release note is grammatically incorrect.

In any other case the release note should be fine.

Behind The Scenes: Kubernetes Release Notes Tips & Tricks - Mike Arpaia, Kolide (KubeCon 2018 Lightning Talk)

Docs: OWNERS Files

Mon, 01 Jan 0001 00:00:00 +0000

Overview

OWNERS files are used to designate responsibility over different parts of the Kubernetes codebase. Today, we use them to assign the reviewer and approver roles (defined in our community membership doc) that are used in our two-phase code review process. Our OWNERS files were inspired by Chromium OWNERS files which in turn inspired GitHub’s CODEOWNERS files

The velocity of a project that uses code review is limited by the number of people capable of reviewing code. The quality of a person’s code review is limited by their familiarity with the code under review. Our goal is to address both of these concerns through the prudent use and maintenance of OWNERS files.

OWNERS spec

The k8s.io/test-infra/prow/repoowners package is the main consumer of OWNERS files. If this page is out of date, look there.

OWNERS

Each directory that contains a unit of independent code or content may also contain an OWNERS file. This file applies to everything within the directory, including the OWNERS file itself, sibling files, and child directories.

OWNERS files are in YAML format and support the following keys:

approvers: a list of GitHub usernames or aliases that can /approve a PR
labels: a list of GitHub labels to automatically apply to a PR
options: a map of options for how to interpret this OWNERS file, currently only one:
- no_parent_owners: defaults to false if not present; if true, exclude parent OWNERS files. Allows the use case where a/deep/nested/OWNERS file prevents a/OWNERS file from having any effect on a/deep/nested/bit/of/code
reviewers: a list of GitHub usernames or aliases that are good candidates to /lgtm a PR
emeritus_approvers a list of GitHub usernames of folks who were previously in the approvers section, but are no longer actively approving code. please see below for more details.

The above keys constitute a simple OWNERS configuration.

All users are expected to be assignable. In GitHub terms, this means they must be members of the organization to which the repo belongs.

A typical OWNERS file looks like:

approvers:
 - alice
 - bob  # this is a comment
reviewers:
 - carol
 - david  # this is another comment
 - sig-foo # this is an alias

Filters

An OWNERS file may also include a filters key. The filters key is a map whose keys are Go regular expressions and whose values are simple OWNERS configurations. The regular expression keys are matched against paths relative to the OWNERS file in which the keys are declared. For example:

filters:
 ".*":
 labels:
 - re/all
 "\\.go$":
 labels:
 - re/go

If you set filters you must not set a simple OWNERS configuration outside of filters.

Note: The options key (e.g., no_parent_owners) is an exception and may be set at the top level even when using filters. All other owner-related keys such as approvers, reviewers, labels, and emeritus_approvers must be defined inside filters.

For example:

# WARNING: This use of 'labels' and 'filters' as siblings is invalid.
labels:
- re/all
filters:
 "\\.go$":
 labels:
 - re/go

Instead, set a .* key inside filters (as shown in the previous example).

Emeritus

It is inevitable, but there are times when someone may shift focuses, change jobs or step away from a specific area in the project for a time. These people may be domain experts over certain areas of the codebase, but can no longer dedicate the time needed to handle the responsibilities of reviewing and approving changes. They are encouraged to add themselves as an “emeritus” approver under the emeritus_approvers key.

GitHub usernames listed under the emeritus_approvers key can no longer approve code (use the /approve command) and will be ignored by prow for assignment. However, it can still be referenced by a person looking at the OWNERS file for a possible second or more informed opinion.

When a contributor returns to being more active in that area, they may be promoted back to a regular approver at the discretion of the current approvers.

emeritus_approvers:
- david  # 2018-05-02
- emily  # 2019-01-05

Cleanup

In addition to the Emeritus process above, from time to time, it is necessary to prune inactive folks from OWNERS files. A core principle in maintaining a healthy community is encouraging active participation. Those listed in OWNERS files have a higher activity requirement, as they directly impact the ability of others to contribute. If anyone listed in OWNERS files should become inactive, here is what we will do:

if the person is in reviewers section, their GitHub id will be removed from the section
if the person is in approvers section, their GitHub id will be moved the emeritus_approvers section.

An inactive person (listed in an OWNERS file) is defined as someone with less than 10 Devstats recorded contributions within the past year, as shown by this dashboard. This is a conservative metric but should ensure only the removal of the most inactive folks from a OWNERS file.

PR comments are less than 10 and Devstats count is less than 10 for a year

OWNERS_ALIASES

Each repo may contain at its root an OWNERS_ALIASES file.

OWNERS_ALIASES files are in YAML format and support the following keys:

aliases: a mapping of alias name to a list of GitHub usernames

We use aliases for groups instead of GitHub Teams, because changes to GitHub Teams are not publicly auditable.

A sample OWNERS_ALIASES file looks like:

aliases:
 sig-foo:
 - david
 - erin
 sig-bar:
 - bob
 - frank

GitHub usernames and aliases listed in OWNERS files are case-insensitive.

Code Review using OWNERS files

This is a simplified description of our full PR testing and merge workflow that conveniently forgets about the existence of tests, to focus solely on the roles driven by OWNERS files. Please see below for details on how specific aspects of this process may be configured on a per-repo basis.

The Code Review Process

The author submits a PR
Phase 0: Automation suggests reviewers and approvers for the PR
- Determine the set of OWNERS files nearest to the code being changed
- Choose at least two suggested reviewers, trying to find a unique reviewer for every leaf OWNERS file, and request their reviews on the PR
- Choose suggested approvers, one from each OWNERS file, and list them in a comment on the PR
Phase 1: Humans review the PR
- Reviewers look for general code quality, correctness, sane software engineering, style, etc.
- Anyone in the organization can act as a reviewer with the exception of the individual who opened the PR
- If the code changes look good to them, a reviewer types /lgtm in a PR comment or review; if they change their mind, they /lgtm cancel
- Once a reviewer has /lgtm‘ed, prow (@k8s-ci-robot) applies an lgtm label to the PR
Phase 2: Humans approve the PR
- The PR author /assign’s all suggested approvers to the PR, and optionally notifies them (eg: “pinging @foo for approval”)
- Only people listed in the relevant OWNERS files, either directly or through an alias, as described above, can act as approvers, including the individual who opened the PR.
- Approvers look for holistic acceptance criteria, including dependencies with other features, forwards/backwards compatibility, API and flag definitions, etc
- If the code changes look good to them, an approver types /approve in a PR comment or review; if they change their mind, they /approve cancel
- prow (@k8s-ci-robot) updates its comment in the PR to indicate which approvers still need to approve
- Once all approvers (one from each of the previously identified OWNERS files) have approved, prow (@k8s-ci-robot) applies an approved label
Phase 3: Automation merges the PR:
- If all of the following are true:
  - All required labels are present (eg: lgtm, approved)
  - Any blocking labels are missing (eg: there is no do-not-merge/hold, needs-rebase)
- And if any of the following are true:
  - there are no presubmit prow jobs configured for this repo
  - there are presubmit prow jobs configured for this repo, and they all pass after automatically being re-run one last time
- Then the PR will automatically be merged

Quirks of the Process

There are a number of behaviors we’ve observed that while possible are discouraged, as they go against the intent of this review process. Some of these could be prevented in the future, but this is the state of today.

An approver’s /lgtm is simultaneously interpreted as an /approve
- While a convenient shortcut for some, it can be surprising that the same command is interpreted in one of two ways depending on who the commenter is
- Instead, explicitly write out /lgtm and /approve to help observers, or save the /lgtm for a reviewer
- This goes against the idea of having at least two sets of eyes on a PR, and may be a sign that there are too few reviewers (who aren’t also approver)
Technically, anyone who is a member of the kubernetes GitHub organization can drive-by /lgtm a PR
- Drive-by reviews from non-members are encouraged as a way of demonstrating experience and intent to become a member or reviewer.
- Drive-by /lgtm’s from members may be a sign that our OWNERS files are too small, or that the existing reviewers are too unresponsive
- This goes against the idea of specifying reviewers in the first place, to ensure that author is getting actionable feedback from people knowledgeable with the code
Reviewers, and approvers are unresponsive
- This causes a lot of frustration for authors who often have little visibility into why their PR is being ignored
- Many reviewers and approvers are so overloaded by GitHub notifications that @mention’ing is unlikely to get a quick response
- An author can work around this by manually reading the relevant OWNERS files, /unassign‘ing unresponsive individuals, and /assign‘ing others
- This is a sign that our OWNERS files are stale; pruning the reviewers and approvers lists would help with this
Authors are unresponsive
- This costs a tremendous amount of attention as context for an individual PR is lost over time
- This hurts the project in general as its general noise level increases over time
- Instead, close PR’s that are untouched after too long (we currently have a bot do this after 90 days)

Automation using OWNERS files

Kubernetes uses the Prow Blunderbuss plugin and Tide. Tide uses GitHub queries to select PRs into “tide pools”, runs as many in a batch as it can (“tide comes in”), and merges them (“tide goes out”).

Blunderbuss plugin:
- responsible for determining reviewers
Tide:
- responsible for automatically running batch tests and merging multiple PRs together whenever possible.
- responsible for retriggering stale PR tests.
- responsible for updating a GitHub status check explaining why a PR can’t be merged (eg: a missing lgtm or approved label)

`prow`

Prow receives events from GitHub, and reacts to them. It is effectively stateless. The following pieces of prow are used to implement the code review process above.

cmd: tide
- per-repo configuration:
  - labels: list of labels required to be present for merge (eg: lgtm)
  - missingLabels: list of labels required to be missing for merge (eg: do-not-merge/hold)
  - reviewApprovedRequired: defaults to false; when true, require that there must be at least one approved pull request review present for merge
  - merge_method: defaults to merge; when squash or rebase, use that merge method instead when clicking a PR’s merge button
- merges PR’s once they meet the appropriate criteria as configured above
- if there are any presubmit prow jobs for the repo the PR is against, they will be re-run one final time just prior to merge
plugin: assign
- assigns GitHub users in response to /assign comments on a PR
- unassigns GitHub users in response to /unassign comments on a PR
plugin: approve
- per-repo configuration:
  - issue_required: defaults to false; when true, require that the PR description link to an issue, or that at least one approver issues a /approve no-issue
  - implicit_self_approve: defaults to false; when true, if the PR author is in relevant OWNERS files, act as if they have implicitly /approve’d
- adds the approved label once an approver for each of the required OWNERS files has /approve’d
- comments as required OWNERS files are satisfied
- removes outdated approval status comments
plugin: blunderbuss
- determines reviewers and requests their reviews on PR’s
plugin: lgtm
- adds the lgtm label when a reviewer comments /lgtm on a PR
- the PR author may not /lgtm their own PR
pkg: k8s.io/test-infra/prow/repoowners
- parses OWNERS and OWNERS_ALIAS files
- if the no_parent_owners option is encountered, parent owners are excluded from having any influence over files adjacent to or underneath of the current OWNERS file

Maintaining OWNERS files

OWNERS files should be regularly maintained.

We encourage people to self-nominate, self-remove or switch to emeritus from OWNERS files via PR’s. Ideally in the future we could use metrics-driven automation to assist in this process.

We should strive to:

grow the number of OWNERS files
add new people to OWNERS files
ensure OWNERS files only contain organization members
ensure OWNERS files only contain people are actively contributing to or reviewing the code they own
remove inactive people from OWNERS files

Bad examples of OWNERS usage:

directories that lack OWNERS files, resulting in too many hitting root OWNERS
OWNERS files that have a single person as both approver and reviewer
OWNERS files that haven’t been touched in over 6 months
OWNERS files that have non organization members present

Good examples of OWNERS usage:

team aliases are used that correspond to sigs
there are more reviewers than approvers
the approvers are not in the reviewers section
OWNERS files that are regularly updated (at least once per release)

Docs: Community Expectations

Mon, 01 Jan 0001 00:00:00 +0000

Kubernetes is a community project. Consequently, it is wholly dependent on its community to provide a productive, friendly and collaborative environment.

The first and foremost goal of the Kubernetes community is to develop orchestration technology that radically simplifies the process of creating reliable distributed systems. However a second, equally important goal is the creation of a community that fosters easy, agile development of such orchestration systems.

We therefore describe the expectations for members of the Kubernetes community. This document is intended to be a living one that evolves as the community evolves via the same PR and code review process that shapes the rest of the project. It currently covers the expectations of conduct that govern all members of the community as well as the expectations around code review that govern all active contributors to Kubernetes.

Code review

As a community we believe in the value of code review for all contributions. Code review increases both the quality and readability of our codebase, which in turn produces high quality software.

See the pull request documentation for more information on code review.

Consequently, as a community we expect that all active participants in the community will also be active reviewers. The community membership outlines the responsibilities of the different contributor roles.

Expect reviewers to request that you avoid common go style mistakes in your PRs.

Expectations of reviewers: Review comments

Because reviewers are often the first points of contact between new members of the community and can significantly impact the first impression of the Kubernetes community, reviewers are especially important in shaping the Kubernetes community.
Reviewers are highly encouraged to not only abide by the code of conduct but are strongly encouraged to go above and beyond the code of conduct to promote a collaborative, respectful Kubernetes community.

Expectations of reviewers: Review latency

Reviewers are expected to respond in a timely fashion to PRs that are assigned to them. Reviewers are expected to respond to an active PRs with reasonable latency, and if reviewers fail to respond, those PRs may be assigned to other reviewers.

If reviewers are unavailable to review for some time, they are expected to set their user status to “busy” so that the bot will not request reviews from them on new PRs automatically. If they are unavailable for a longer period of time, they are expected to remove themselves from the OWNERS file and potentially nominate someone else.

Active PRs are considered those which have a proper CLA (cla:yes) label and do not need rebase to be merged. PRs that do not have a proper CLA, or require a rebase are not considered active PRs.

Thanks

Many thanks in advance to everyone who contributes their time and effort to making Kubernetes both a successful system as well as a successful community. The strength of our software shines in the strengths of each individual community member.
Thanks!

Kubernetes Contributors – Getting Started

Docs: Making your First Contribution

Your First Contribution

Find something to work on

Find a good first topic

Issue Assignment in Github

Learn about SIGs

SIG structure

Find a SIG that is related to your contribution

SIG-specific contributing guidelines

File an Issue

Docs: Contributing to Kubernetes

Contributing

Communication

GitHub workflow

Opening a Pull Request

Code Review

Best practices

Testing

Security

Documentation

Issues Management or Triage

Docs: Platforms Guide

Adding supported platforms

Step 0: Engage with the community

Step 1: Building

Step 2: Testing

Step 3: Releasing

Step 4: Finishing

Deprecating and removing supported platforms

Docs: Pull Request Process

Before You Submit a Pull Request

Run Local Verifications

The Pull Request Submit Process

Marking Unfinished Pull Requests

Pull Requests and the Release Cycle

Comment Commands Reference

Automation

How the e2e Tests Work

Why was my pull request closed?

Why is my pull request not getting reviewed?

Best Practices for Faster Reviews

Familiarize yourself with project conventions

Is the feature wanted? File a Kubernetes Enhancement Proposal

KISS, YAGNI, MVP, etc.

Smaller Is Better: Small Commits, Small Pull Requests

Open a Different Pull Request for Fixes and Generic Features

Don’t Open Pull Requests That Span the Whole Repository

Comments Matter

Test

Squashing

Commit Message Guidelines

Try to keep the subject line to 50 characters or less; do not exceed 72 characters

Providing additional context

The first word in the commit message subject should be capitalized unless it starts with a lowercase symbol or other identifier

Do not end the commit message subject with a period

Use imperative mood in your commit message subject

Add a single blank line before the commit message body

Wrap the commit message body at 72 characters

Do not use GitHub keywords or (@)mentions within your commit message

GitHub Keywords

(@)Mentions

Use the commit message body to explain the what and why of the commit

It’s OK to Push Back

Common Sense and Courtesy

Trivial Edits

Large or Automatic Edits

AI Guidance

Fixing Linter Issues

The Testing and Merge Workflow

More About Ok-To-Test

Docs: GitHub Workflow

1. Fork in the cloud

2. Clone fork to local storage

3. Create a Working Branch

Building Kubernetes

4. Keep your branch in sync

5. Commit Your Changes

6. Push to GitHub

7. Create a Pull Request

More About `Ok-To-Test`