Welcome to the Kubeflow project! This document is the single source of truth for how to contribute to the code base. We’d love to accept your patches and contributions to this project. There are just a few small guidelines you need to follow.
Contributions to this project must be accompanied by a Contributor License Agreement. You (or your employer) retain the copyright to your contribution, this simply gives us permission to use and redistribute your contributions as part of the project. Head over to https://cla.developers.google.com/ to see your current agreements on file or to sign a new one.
You generally only need to submit a CLA once, so if you’ve already submitted one (even if it was for a different project), you probably don’t need to do it again.
Please make sure to read and observe our Code of Conduct.
Maggie Lynn, a user experience researcher, is conducting user studies to inform future developments for Kubeflow. These typically involve a one hour study session conducted online with a thank you gift for providing your feedback. As a member of the Kubeflow community, your feedback and expertise are extremely valuable to us, so if you have time in the next month, please consider participating. To gather your interest, availability, and some basic information about you, please fill out this form where you’ll find out more details about this research opportunity: https://goo.gl/forms/sv5sRo3UfsgeUEjK2
Help is always welcome! For example, documentation (like the text you are reading now) can always use improvement. There’s always code that can be clarified and variables or functions that can be renamed or commented. There’s always a need for more test coverage. You get the idea - if you ever see something you think should be fixed, you should own it. Here is how you get started.
Kubeflow issues that would make good entry points can be found by looking at the following tags:
Follow these instructions if
Please send a PR adding yourself to members
If you would like your company or organization to be acknowledged for contributing to Kubeflow or participatng in the community (being a user counts) please send a PR adding the relevant info tomember_organizations.yaml.
OWNERS files are used to designate responsibility over different parts of the Kubeflow codebase. Today, we use them to assign the reviewer and approver roles 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
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
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
falseif not present; if
true, exclude parent OWNERS files. Allows the use case where
a/OWNERSfile from having any effect on
reviewers: a list of GitHub usernames or aliases that are good candidates to
All users are expected to be assignable. In GitHub terms, this means they are either collaborators of the repo, or members of the organization to which the repo belongs.
A typical OWNERS file looks like:
approvers: - alice - bob # this is a comment reviewers: - alice - carol # this is another comment - sig-foo # this is an alias
Each repo may contain at its root an OWNERS_ALIAS file.
OWNERS_ALIAS 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_ALISES file looks like:
aliases: sig-foo: - david - erin sig-bar: - bob - frank
GitHub usernames and aliases listed in OWNERS files are case-insensitive.
/lgtmin a PR comment or review; if they change their mind, they
/lgtm‘ed, prow (@k8s-ci-robot) applies an
lgtmlabel to the PR
/assign’s all suggested approvers to the PR, and optionally notifies them (eg: “pinging @foo for approval”)
/approvein a PR comment or review; if they change their mind, they
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.
/lgtmis simultaneously interpreted as an
/approveto help observers, or save the
/lgtmfor a reviewer
/lgtm’s from members may be a sign that our OWNERS files are too small, or that the existing reviewers are too unresponsive
/assign’s a PR, reviewers and approvers will be made aware of it on their PR dashboard
/unassign‘ing unresponsive individuals, and
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.
labels: list of labels required to be present for merge (eg:
missingLabels: list of labels required to be missing for merge (eg:
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
rebase, use that merge method instead when clicking a PR’s merge button
/assigncomments on a PR
/unassigncomments on a PR
issue_required: defaults to
true, require that the PR description link to an issue, or that at least one approver issues a
implicit_self_approve: defaults to
true, if the PR author is in relevant OWNERS files, act as if they have implicitly
approvedlabel once an approver for each of the required OWNERS files has
lgtmlabel when a reviewer comments
/lgtmon a PR
/lgtmtheir own PR
no_parent_ownersoption is encountered, parent owners are excluded from having any influence over files adjacent to or underneath of the current OWNERS file
OWNERS files should be regularly maintained.
We encourage people to self-nominate or self-remove 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:
Bad examples of OWNERS usage:
Good examples of OWNERS usage:
approversare not in the