Knative contributor guidelines

So, you want to hack on Knative? Yay!

The following sections outline the process all changes to the Knative repositories go through. All changes, regardless of whether they are from newcomers to the community or from the core team follow the same process and are given the same level of review.

Working groups

The Knative contributors community is organized into a set of working groups. Any contribution to Knative should be started by first engaging with the appropriate working group.

Code of conduct

All members of the Knative community must abide by the Code of Conduct. Only by respecting each other can we develop a productive, collaborative community.

Team values

We promote and encourage a set of shared values to improve our productivity and inter-personal interactions.

Contributor license agreements

We'd love to accept your patches! But before we can take them, you will have to fill out the Google CLA. (Make sure to fill out the CLA with the same email address you used to register for Github.)

Once you are CLA'ed, we'll be able to accept your pull requests. This is necessary because you own the copyright to your changes, even after your contribution becomes part of this project. So this agreement simply gives us permission to use and redistribute your contributions as part of the project.

Note: Your contributions are verified using the email address for which you use to sign the CLA. Therefore, setting your GitHub account to private is unsupported because all commits from private accounts are sent from the noreply email address.

Design documents

Any substantial design deserves a design document (template). Design documents are written with Google Docs and should be shared with the community by adding the doc to our Team Drive and sending an email to the appropriate working group's mailing list to let people know the doc is there. To get write access to the drive, you'll need to be a member of the Knative organization.

The team drive is shared with the knative-users@ and knative-dev@ Google groups for reading and editing, respectively. Access to knative-users@ is unlimited, while knative-dev@ requires human review. If you're not part of one of those groups, the first time you try to access the team drive or a specific doc, you'll be asked to request permission. Please join one of the above groups (you can join knative-users and later join knative-dev if you want immediate access).

Contributing documentation

For more information about contributing to the Knative documentation, see DOCS-CONTRIBUTING. A lot of the information on this page still applies, but you'll find the specifics about the docs process there.

Contributing a feature

The process for adding features to Knative can be found here.

Setting up to contribute to Knative

Check out this README to learn about the Knative source base and setting up your development environment.

Pull requests

We have a gubernator instance that provides a pull request dashboard so you can see which PRs you need to take action on.

If you're working on an existing issue, simply respond to the issue and express interest in working on it. This helps other people know that the issue is active, and hopefully prevents duplicated efforts.

To submit a proposed change:

  • Fork the affected repository.
  • Create a new branch for your changes.
  • Develop the code/fix.
  • Add new test cases. In the case of a bug fix, the tests should fail without your code changes. For new features try to cover as many variants as reasonably possible.
  • Modify the documentation as necessary.
  • Verify all CI status checks pass, and work to make them pass if failing.

The general rule is that all PRs should be 100% complete - meaning they should include all test cases and documentation changes related to the change. A significant exception is work-in-progress PRs. These should be indicated by a [WIP] prefix in the PR title. WIP PRs should not be merged as long as they are marked WIP.

When ready, if you have not already done so, sign a contributor license agreement and submit the PR.

This project uses Prow to assign reviewers to the PR, set labels, run tests automatically, and so forth.

See Reviewing and Merging Pull Requests for the PR review and merge process used for Knative and for more information about Prow.

Issues

GitHub issues can be used to report bugs or submit feature requests.

When reporting a bug please include the following key pieces of information:

  • The version of the project you were using (version number, git commit, etc)
  • Operating system you are using
  • The exact, minimal, steps needed to reproduce the issue. Submitting a 5 line script will get a much faster response from the team than one that's hundreds of lines long.

Third-party code

  • All third-party code must be placed in vendor/ or third_party/ folders.
  • vendor/ folder is managed by dep and stores the source code of third-party Go dependencies. vendor/ folder should not be modified manually.
  • Other third-party code belongs in third_party/ folder.
  • Third-party code must include licenses.

A non-exclusive list of code that must be places in vendor/ and third_party/:

  • Open source, free software, or commercially-licensed code.
  • Tools or libraries or protocols that are open source, free software, or commercially licensed.
  • Derivative works of third-party code.
  • Excerpts from third-party code.

Adding a new third-party dependency to third_party/ folder

  • Create a sub-folder under third_party/ for each component.
  • In each sub-folder, make sure there is a file called LICENSE which contains the appropriate license text for the dependency. If one doesn't exist then create it. More details on this below.
  • Check in a pristine copy of the code with LICENSE and METADATA files. You do not have to include unused files, and you can move or rename files if necessary, but do not modify the contents of any files yet.
  • Once the pristine copy is merged into master, you may modify the code.

LICENSE

The license for the code must be in a file named LICENSE. If it was distributed like that, you're good. If not, you need to make LICENSE be a file containing the full text of the license. If there's another file in the distribution with the license in it, rename it to LICENSE (e.g., rename a LICENSE.txt or COPYING file to LICENSE). If the license is only available in the comments or at a URL, extract and copy the text of the license into LICENSE.

You may optionally document the generation of the LICENSE file in the local_modifications field of the METADATA file.

If there are multiple licenses for the code, put the text of all the licenses into LICENSE along with separators and comments as to the applications.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License.