Contributing to Kubernetes

An entrypoint to getting started with contributing to the Kubernetes project.

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:

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

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.