Getting Started on Kubernetes Contributors

Making your First Contribution

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

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)!

Contributing to Kubernetes

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

Communication
GitHub workflow
Open a Pull Request
Code Review
Best Practices
Testing
Security
Documentation
Issues Management or Triage

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.

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.

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
- Run Local Verifications
The Pull Request Submit Process
Why was my pull request closed?
Why is my pull request not getting reviewed?
Best Practices for Faster Reviews
The Testing and Merge Workflow
- More About Ok-To-Test

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 .

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”.

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.

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.

Issue Triage Guidelines

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

Scope
What Is Triaging?
Why Is Triaging Beneficial?
How to Triage: A Step-by-Step Flow
- Triage-Related Tools
- Process Pointers and Advice from SIGs
  - Running a Triage Meeting: Tips from api-machinery
  - Triage Guide by cluster-lifecycle
Step One: Review Newly Created Open Issues
- Conducting Searches
Step Two: Triage Issues by Type
Step Three: Define Priority
Step Four: Find and Set the Right SIG(s) to Own an Issue
- Self-Assigning
Step Five: Follow Up
Further Notes
- Support Requests: Channels
- User Support Response: Example

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.

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.

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:

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.

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.

Getting Started on Kubernetes Contributors

Making your First Contribution

Find something to work on

Contributing to Kubernetes

Platforms Guide

Adding supported platforms

Pull Request Process

Before You Submit a Pull Request

GitHub Workflow

1. Fork in the cloud

2. Clone fork to local storage

3. Create a Working Branch

Coding Conventions

Code conventions

Testing conventions

Directory and file conventions

Help Wanted and Good First Issue Labels

Overview

Issue Triage Guidelines

Table of Contents

Scope

Non-code Contributions

What is this?

Adding Release Notes

Does my pull request need a release note?

OWNERS Files

Overview

Community Expectations