Skip to content

Latest commit

 

History

History
95 lines (60 loc) · 8.14 KB

CONTRIBUTING.md

File metadata and controls

95 lines (60 loc) · 8.14 KB
Raw

Overview

The purpose of this document is to give guidance to the Kyma contributors. All the rules are listed and explained here, and all contributors and maintainers must follow them.

Naming guidelines

To learn how to name objects in this project, see the naming document.

Documentation types

The main README.md document in the templates subfolder in this repository contains an overview of document templates used in specific Kyma repositories. The templates themselves are collected in the resources subfolder.

Extend the list whenever you define a new template for other document types. Make sure to update the table in the README.md document after you add new templates to the resources subfolder.

Agreements and licenses

Read the subsections to learn the details of the agreements to submit and licences to comply with as a Kyma contributor.

Individual contributor license agreement

As a Kyma contributor, you must accept the Kyma project's licenses and submit the Individual Contributor License Agreement before you contribute code or content to any Kyma repository. Kyma maintainers will not accept contributions made without such a consent. This applies to all contributors, including those contributing on behalf of a company. If you agree to the content of the Agreement, click on the link posted by the CLA assistant as a comment to the pull request. Click it to review the CLA and accept it on the next screen if you agree to it. The CLA assistant will save your decision for the upcoming contributions and will notify you if there is any change to the CLA in the meantime.

Corporate contributor license agreement

Employees of a company who contribute code need to submit one company agreement in addition to the individual agreement above. This is mainly for the protection of the contributing employees.

An authorized company representative needs to download, fill in, and print the Corporate Contributor License Agreement form. Scan it and send it to info@kyma-project.io. The form contains a list of employees who are authorized to contribute on behalf of your company. To report any changes on the list, contact info@kyma-project.io.

Contribution rules

If you are a contributor, follow these basic rules:

  • The contribution workflow in all Kyma repositories bases on the principles of the GitHub Flow. Thus, the master branch is the most important one. Avoid working directly on it. When you work on new features or bug fixes, work on separate branches.
  • Work on forks of Kyma repositories.
  • Squash and rebase every pull request before merging.
  • You can merge a pull request if you receive an approval from at least one code owner from each part of the repository to which you contribute in your pull request.

Every contributor commits to the following agreement:

  • In each pull request, include a description or a reference to a detailed description of the steps that the maintainer goes through to check if a pull request works and does not break any other functionality.
  • Provide clear and descriptive commit messages.
  • Follow the squash and rebase process.
  • Follow the accepted documentation rules and use appropriate templates.
  • Choose the proper directory for the content of your pull request, depending on the role of the component, and how it relates to the project structure.
  • As the creator of the pull request, you are responsible for ensuring that the pull request follows the correct review and approval flow.
  • Make sure that the person who owns the documentation, such as a technical writer, reviews the changes in the documentation before you merge the pull request.

Contribution process

This section explains how you can contribute code or content to any Kyma repository, propose an improvement, or report a bug. The contributing process applies both to the members of the Kyma organization and the external contributors.

Contribute code or content

To contribute code or content to a given Kyma repository, follow these steps:

  1. Make sure that the change is valid and approved. If you are an external contributor, open a GitHub issue before you make a contribution.
  2. Fork the Kyma repository that you want to contribute to.
  3. Clone it locally, add a remote upstream repository for the original repository, and set up the master branch to track the remote master branch from the upstream repository. See the git-workflow document to learn how to configure your fork.
  4. Create a new branch out of the local master branch of the forked repository.
  5. Commit and push changes to your new branch. Create a clear and descriptive commit message in which you specify what you have changed. See the git-workflow.md document for commit message guidelines.
  6. Create a pull request from your branch on the forked repository to the master branch of the original, upstream repository. Fill in the pull request template according to instructions.
  7. Read and accept the Contributor Licence Agreement (CLA).
  8. If there are merge conflicts on your pull request, squash your commits and rebase the master branch.
  9. In your pull request:
  • Provide a reference to any related GitHub issue.
  • Make sure that the Allow edits from maintainers option is selected to allow upstream repository maintainers, and those with the push access to the upstream repository, to commit to your forked branch.
  • Choose at least one area/{capability} label from the available list and add it to your pull request to categorize changes you made. Labels are required to include your pull request in the CHANGELOG.md file, and classify it accordingly.
  1. Run the relevant CI job manually. If you are an external contributor, contact the repository maintainers specified in the CODEOWNERS file to do it for you.
  2. Wait for the Kyma maintainers to review and approve your pull request. The maintainers can approve it, request enhancements to your change, or reject it.

NOTE: The reviewer must check if the related CI job and tests have completed successfully before approving the pull request.

  1. When the maintainers approve your change, merge the pull request. If you are an external contributor, contact the repository maintainers specified in the CODEOWNERS file to do the merge.

Report an issue

If you find a bug to report or you want to propose a new feature, go to the GitHub issue tracker of a given repository and create an issue. If you are not certain which repository your bug or feature relates to, raise it on the kyma repository.

NOTE: The repository maintainers handle only well-documented, valid issues that have not been reported yet. Before you create one, check if there are no duplicates. Provide all details and include examples. When you report a bug, list the exact steps necessary to reproduce it.

See the issues-workflow document for details on issues triage and processing workflow.

Maintenance rules

Every maintainer reviews each contribution according to the rules listed in this document.

Although it is the responsibility of the owner of the pull request to ensure that the maintainers review and approve the pull request, maintainers need to coordinate the overall number of unreviewed and unapproved pull requests in their queue, and, if required, take appropriate measures to handle them effectively.

To learn more about maintainers' responsibilities and rules for appointing new maintainers, and removing the existing ones, refer to the governance.md document.

Owners

To identify the owners of particular parts of your repository, see the CODEOWNERS file in the root directory.