Kubernetes Contributor Cheat Sheet
A list of common resources when contributing to Kubernetes, tips, tricks, and common best practices used within the Kubernetes project. It is a “TL;DR” or quick reference of useful information to make your GitHub contribution experience better.
Table of Contents
- Helpful Resources
- Communicating Effectively on GitHub
- Submitting a Contribution
- Working Locally
- Contributor Course - NEW - The E-Learning for Contributors course for Kubernetes!
- Contributor Guide - Guide on how to begin contributing to Kubernetes Project.
- Developer Guide - Guide to contributing code directly to the Kubernetes Project.
- Security and Disclosure Information - Guide for reporting vulnerabilities and the security release process.
SIGs and Other Groups
- Calendar - View all the Kubernetes Community events (SIG/WG meetings, events etc.)
- kubernetes-dev - The Kubernetes development mailing list
- Kubernetes Forum - Official Kubernetes forum.
- Slack channels - Official Kubernetes Slack.
- Stack Overflow - A place to ask your Kubernetes end-user questions.
- YouTube Channel - Official channel for the Kubernetes community.
- Prow - Kubernetes CI/CD System.
- Tide - Prow plugin that manages merges and tests. Tide Dashboard
- Bot commands - Commands used to interact with Kubernetes Bots (examples:
- GitHub labels - List of labels used throughout the Kubernetes Project
- Kubernetes Code Search, maintained by @dims
- Prow - Kubernetes CI/CD System.
- Test Grid - View historical tests and their associated information.
- Triage Dashboard - Aggregates similar failures together for better troubleshooting.
Important Email Aliases
- email@example.com - Mail someone on the community team (SIG Contributor Experience) about a community issue.
- firstname.lastname@example.org - Contact the Code of Conduct committee, private mailing list.
- email@example.com - Mail the GitHub Administration Team privately, for sensitive items.
- firstname.lastname@example.org - Mail the steering committee. Public address with public archive.
- email@example.com - Mail the steering committee privately, for sensitive items.
- firstname.lastname@example.org - Contact the CNCF social team; blog, twitter account, and other social properties.
Other Useful Links
- Developer Statistics - View developer statistics for all CNCF managed projects.
- Kubernetes Patch Release Schedule and team contact information for Kubernetes patch releases.
Communicating Effectively on GitHub
How to be Excellent to Each Other
As a first step, familiarize yourself with the Code of Conduct.
Examples of Good/Bad Communication
When raising an issue, or seeking assistance, please be polite with your request:
🙂 “X doesn’t compile when I do Y, do you have any suggestions?”
😞 “X doesn’t work! Please fix it!”
When closing a PR, convey an explanatory and cordial message explaining why it does not meet the requirements to be merged.
🙂 “I’m closing this PR because this feature can’t support the use case X. In its proposed form, it would be better to implement with Y tool. Thank you for working on this.”
😞 “Why isn’t this following the API conventions? This should be done elsewhere!”
Submitting a Contribution
Signing the CLA
Before you can submit a contribution, you must sign the Contributor License Agreement(CLA). The Kubernetes project can only accept a contribution if you or your company have signed the CLA.
Should you encounter any problems signing the CLA, follow the CLA troubleshooting guidelines.
Opening and Responding to Issues
GitHub Issues are the primary means of tracking things such as bug reports, enhancement requests, or reporting other issues such as failing tests. They are not intended for user support requests. For those, please check with the troubleshooting guide, report the problem to Stack Overflow, or follow up on the Kubernetes forum.
Creating an Issue
- Use an issue template if one is available. Using the correct one will aid other
contributors in responding to your issue.
- Follow any directions described in the issue template itself.
- Be descriptive with the issue you are raising.
- Assign appropriate labels. If you are unsure, the k8s-ci-robot bot (Kubernetes CI bot) will reply to your issue with the needed labels for it to be effectively triaged.
- Be selective when assigning issues using
/cc @<username>. Your issue will be triaged more effectively applying correct labels over assigning more people to the issue.
Responding to an Issue
- When tackling an issue, comment on it letting others know you are working on it to avoid duplicate work.
- When you have resolved something on your own at any future time, comment on the issue letting people know before closing it.
- Include references to other PRs or issues (or any accessible materials), example: “ref: #1234”. It is useful to identify that related work has been addressed somewhere else.
Opening a Pull Request
Pull requests (PR) are the main means of contributing code, documentation or other forms of work that would be stored within a git repository.
Creating a Pull Request
- Follow the directions of the pull request template if one is available. It will help those who respond to your PR.
- If a trivial fix such as a broken link, typo, or grammar mistake, review the entire document for other potential mistakes. Do not open multiple PRs for small fixes in the same document.
- Reference any issues related to your PR, or issues that PR may solve.
- Avoid creating overly large changes in a single commit. Instead, break your PR into multiple small, logical commits. This makes it easier for your PR to be reviewed.
- Comment on your own PR where you believe something may need further explanation.
- Be selective when assigning your PR with
/assign @<username>. Assigning excessive reviewers will not yield a quicker PR review.
- If your PR is considered a “Work in progress” prefix the name with
[WIP]or use the
/holdcommand. This will prevent the PR from being merged till the
[WIP]or hold is lifted.
- If you have not had your PR reviewed, do not close and open a new PR with the
same changes. Ping your reviewers in a comment with
- If your PR isn’t getting enough attention, post a link to the PR in the
#pr-reviewschannel on Slack to find additional reviewers.
Example PR Description
Ref. #3064 #3097
All files owned by SIG testing were moved from `/devel` to the new folder `/devel/sig-testing`.
/cc @stakeholder1 @stakeholder2
/assign @approver1 @approver2 @approver3
What’s in that PR:
- Line 1 - Reference to other issues or PRs (#3064 #3097).
- Line 2 - A brief description of what is being done in the PR.
- Line 4 - SIG assignment with the command
- Line 5 - Reviewers that may have interest in this specific issue or PR are
specified with the
- Line 6 - The
/kind cleanupcommand adds a label that categorizes issues or PR as related to cleaning up code, process, or technical debt.
- Line 7 - The
/area developer-guidecommand categorizes issue or PR as related to the developer guide.
- Line 8 - The command
/assignassigns an approver to the PR. An approver will be suggested by the k8s-ci-robot and is selected from the list of owners in the OWNERS file. They will add the
/approvelabel to the PR after it has been reviewed.
Troubleshooting a Pull Request
After your PR is proposed, a series of tests are executed by the Kubernetes CI platform, Prow. If any of the tests failed, the k8s-ci-robot will reply to the PR with links to the failed tests and available logs.
Pushing new commits to your PR will automatically trigger the tests to re-run.
Occasionally there can be issues with the Kubernetes CI platform. These can occur
for a wide variety of reasons even if your contribution passes all local
tests. You can trigger a re-run of the tests with the
For more information on troubleshooting specific tests, see the Testing Guide.
Kubernetes uses labels to categorize and triage issues and Pull Requests. Applying the right labels will help your issue or PR be triaged more effectively.
Frequently used labels:
/sig <sig name>Assign a SIG to the ownership of the issue or PR.
/area <area name>Associate the issue or PRs to a specific area.
/kind <category>Categorizes the issue or PR.
Before you propose a pull request, you will have to do some level of work locally. If you are new to git, the Atlassian git tutorial is a good starting point. As an alternative, Stanford’s Git magic tutorial is a good multi-language option.
The Kubernetes project uses a “Fork and Pull” workflow that is standard to
GitHub. In git terms, your personal fork is referred to as the "
the actual project’s git repository is called "
upstream". To keep your
personal branch (
origin) up to date with the project (
upstream), it must be
configured within your local working copy.
upstream as a remote, and configure it so you cannot push to it.
# replace <upstream git repo> with the upstream repo URL
git remote add upstream <upstream git repo>
git remote set-url --push upstream no_push
This can be verified by running
git remote -v which will list your configured
Keeping Your Fork in Sync
Fetch all the changes from
upstream and “rebase” them on your local
branch. This will sync your local repo with the
upstream project. Push the local changes to your
git fetch upstream
git checkout master
git rebase upstream/master
You should do this minimally before creating a new branch to work on your feature or fix.
git checkout -b myfeature
The main purpose of squashing commits is to create a clean readable git history or log of the changes that were made. Usually, this is done in the last phase of a PR revision. If you are unsure if you should squash your commits, it is better to err on the side of having more and leave it up to the judgment of the other contributors assigned to review and approve your PR.
Perform an interactive rebase to choose which commits you want to keep and which you want to squash, then force push your branch:
git rebase -i HEAD~3
git push --force
Note: you can also ask your reviewer to add the
tide/merge-method-squash label to your PR (this can be done by a reviewer by issuing the command:
/label tide/merge-method-squash), this will let the bot take care of squashing all commits that are part of this PR and will not result in removal of the
LGTM label (if already applied) or re-run of the CI tests.
Was this page helpful?