Contributing

Overview

Read the Contributing section to understand the Code of Conduct and contribution rules in Kyma. Also, learn some best practices covering Git workflow.

Code of Conduct

This document makes a reference to the rules of behavior for all contributors and maintainers in the community. All members agree to follow them to foster the growth of the community of tolerance, respect, and mutual understanding.

In the attempt to adopt the best practices from the most renowned open-source and cloud-native projects, and work closely with the Cloud Native Computing Foundation (CNCF), our community members undertake to follow the rules outlined in the CNCF Code of Conduct. Read it to learn about the harassment-free environment, examples of unacceptable behavior, and the responsibilities of the project maintainers.

NOTE: If you observe any instance of abusive, harassing, or otherwise unacceptable behavior, report it as an issue to the project maintainers specified in the CODEOWNERS document.

Contributing rules

As a Kyma contributor, you must follow certain guidelines and rules.

Guidelines

Go to the Guidelines section to read about rules and tips for providing content and code to the Kyma repositories. Also, learn how to create a new repository, and how the release process looks in Kyma. Make your life easier using various document types templates prepared for those who would like to contribute.

Documentation types

Read an overview of document templates used in specific Kyma repositories. The templates themselves are collected in the resources subfolder in the community repository.

Extend the list whenever you define a new template for other document types. Make sure to update one of the tables in the Document types templates 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 consent. This applies to all contributors, including those contributing on behalf of a company. If you agree to the content of the Agreement, click the link posted by the CLA assistant as a comment to the pull request (PR). The CLA assistant saves your decision for future contributions and notifies 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.
  • You can merge a PR if you receive an approval from at least one code owner from each part of the repository to which you contribute in your PR.

Every contributor commits to the following agreement:

  • In every PR, include a description or a reference to a detailed description of the steps that the maintainer goes through to check if a PR works and does not break any other functionality.
  • Provide clear and descriptive commit messages.
  • Label your PRs.
  • Follow the accepted documentation rules and use appropriate templates.
  • As the creator of the PR, you are responsible for ensuring that the PR follows the correct review and approval flow.

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 document for commit message guidelines.
  6. Create a PR from your branch on the forked repository to the master branch of the original, upstream repository. Fill in the PR template according to instructions.
  7. Read and accept the Contributor Licence Agreement (CLA).
  8. If there are merge conflicts on your PR, squash your commits and rebase the master branch.
  9. In your PR:
  • 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 PR to categorize changes you made. Labels are required to include your PR in the CHANGELOG.md file and classify it accordingly.
  1. After you create a PR, relevant CI tests need to complete successfully.
  • If you are a Kyma organization member, all related CI tests run automatically after you create a PR. If a test fails, check the reason by clicking the Details button next to the given job on your PR. Make the required changes and the tests rerun. If you want to run a specific test, add the /test {test-name} or /retest {test-name} comment to your PR. To rerun all failed tests, add the /retest comment.
  • If you are an external contributor, contact the repository maintainers specified in the CODEOWNERS file to review your PR and add the /test all comment to your PR to trigger all tests. A Kyma organization member needs to rerun the tests manually each time you commit new changes to the PR.
  1. Wait for the Kyma maintainers to review and approve your PR. The maintainers can approve it, request enhancements to your change, or reject it.

NOTE: The reviewer must check if all related CI tests have completed successfully before approving the PR.

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

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.

NOTE: The community is relentless about Kyma security. To report a sensitive security issue, send an email with details directly to kyma-security@googlegroups.com instead of using a public issue tracker.

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 PR to ensure that the maintainers review and approve the PR, maintainers need to coordinate the overall number of unreviewed and unapproved PRs 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 Kyma working model document.

Maintainers

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

Git workflow

This document is the best practice guide that contains the rules to follow when working with Kyma repositories.

Basic rules

Each contributor and maintainer in Kyma must follow this workflow:

  • Work on forked repositories.
  • Create branches on the fork and avoid working directly on the master branch.
  • Squash and rebase your commits before you merge your pull request.

Benefits

The unified workflow has the following benefits:

  • It encourages external contribution.
  • The history of commits and merges is clean and readable.
  • There are fewer merge conflicts and, when they appear, they are easier to solve.

Prepare the fork

A fork is a copy of the repository from which you raise pull requests to propose changes to the original repository. The unified Kyma contribution workflow that bases on forks allows both the members of the Kyma organization and the external contributors to contribute code and content through the same process. This keeps the main repositories clean as contributors create branches only on the forked repositories.

NOTE: This guide aims to explain how to work with forks on your local copy of the repository. In case you are a contributor who suggests minor changes using GitHub UI, it is recommended to use a Pull bot. This bot keeps your fork up to date by creating and merging a pull request with latest changes into the master branch of your fork.

Steps

NOTE: The document refers to the original repository as the upstream repository and to the forked repository as the origin repository.

Fork a Kyma repository, clone it locally and configure the remote before you start to contribute.

NOTE: When you use two-factor authentication, generate an SSH key and add it to your GitHub account. Use the SSH address to clone the forked repository.

Perform these steps when you configure the fork for the first time:

  1. Fork a repository.

In GitHub, locate the Kyma repository you want to work on and click the Fork button in the upper-right corner of the repository's main page.

  1. Clone the fork to your local machine.

To introduce changes locally, clone the forked repository on your local machine. On GitHub repository's main page, select the Clone and download option to copy the fork's HTTPS address. Use either the terminal and the git clone https://github.com/{your-username}/{your-fork-name}.git command or the Git GUI to clone the forked repository.

  1. Add a Git remote for the original repository.

Configure a remote repository that points to the upstream repository. This allows you to synchronize changes you make on the fork with the original repository.

In the terminal, navigate to the location of your fork and perform the following steps:

  • Run the git remote -v command to list the current configured remote repository for your fork.

The result is as follows:

Click to copy
origin  https://github.com/{your-username}/{your-fork}.git (fetch)
origin  https://github.com/{your-username}/{your-fork}.git (push)

See the example:

Click to copy
origin	https://github.com/i000000/community.git (fetch)
origin	https://github.com/i000000/community.git (push)
  • Specify a new remote upstream repository to synchronize with the fork:
Click to copy
git remote add upstream https://github.com/{original-owner}/{original-repository}.git

See the example:

Click to copy
git remote add upstream https://github.com/kyma-project/community.git
  • Verify the new upstream repository using the git remote -v command.

The result is as follows:

Click to copy
origin    https://github.com/{your-username}/{your-fork}.git (fetch)
origin    https://github.com/{your-username}/{your-fork}.git (push)
upstream  https://github.com/{original-owner}/{original-repository}.git (fetch)
upstream  https://github.com/{original-owner}/{original-repository}.git (push)

  1. Run the git fetch --all command to fetch all remote branches.

  2. Set up the local master branch to track the remote master branch from the upstream repository:

Click to copy
git branch -u upstream/master master

Now, each time you rebase or check out the master branch, you refer to the master branch of the upstream repository.

To verify that your local master branch points to the upstream/master, run the git branch -vv command.

The result is similar to the following:

Click to copy
* master           c2226e0 [upstream/master] Update the README.md document

Contribute

After you set up your fork, start contributing code and content.

Follow these steps:

  1. Create a branch on your fork.

  2. Commit changes.

Always provide clear commit messages to track commit changes easier.

  1. Push the changes.

Push the changes to the remote forked repository. Use the Git GUI or the terminal.

NOTE: Before you push local changes, make sure you are on the branch you are currently working on. Do not push any changes from the master branch.

If you push local changes from the terminal to your remote fork for the first time, use this command:

Click to copy
git push -u origin {branch-name}

Use the git push command to push any further commits made on your local branch to a remote repository.

  1. Open a pull request.

Create a pull request from the branch of your forked repository to the master branch of the upstream repository and wait for the maintainers' review.

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 the pull request works and does not break any other functionality.

    Subject line:

    • Include a short description of changes made.
    • Use the imperative mood.
    • Limit the line to 50 characters.
    • Capitalize it.
    • Do not end the subject line with a period.

    Pull request body:

    • If you made multiple changes and the changes refer to different files, provide details in the pull request body.
    • Use the body to explain what and why, rather than how.
    • Use bullet points for a list of items.
    • List any side effects or other unintuitive consequences of this change.

  • Put references to any related issues at the end of the pull request body. For example, write Resolves #123, Fixes #43, or See also #33.

  • Make sure that the Allow edits from maintainers option is selected to allow upstream repository maintainers, and users with 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.

NOTE: Steps 5 and 6 are optional. Follow them if you have merge conflicts on your pull request.

  1. Squash your commits.

Follow these steps:

Click to copy
git log # Check the log for the commits history and get the number of your commits that you need to squash. Do not squash commits that are not yours.

Press q to exit the log.

Click to copy
git rebase HEAD~{number} -i # Enter the interactive mode to squash the number of commits. For example, to enter interactive mode and squash the last three commits:
git rebase HEAD~3 -i

Leave the top commit, and squash the remaining ones by changing the pick command to squash. To change the command, type cw and then enter s in place of pick. Press esc to exit the insert mode, move to the line with the next commit, and enter . to make the same change there. Repeat the same action with all the remaining commits. When you finish, save the changes and exit the editor by pressing :wq.

This process squashes all your commits into the top one. Now you can adjust the commit message. Enter the insert mode by typing i and change the commit message. The first line is the commit subject. If you want to provide more details, add the commit body in the next lines. Always separate the commit subject from the commit body with a blank line. When you finish, press esc to exit the insert mode. Then save the changes and exit the editor by typing :wq.

See how to squash your commits step-by-step in this video:

Squash

  1. Rebase the master branch.

After you squash commits on your branch into one commit, reapply it on the top of the master branch. Follow this process:

Click to copy
git checkout master # Switch to the master branch.
git pull # Update the master branch by pulling all changes.
git checkout {branch-name} # Switch back to your branch.
git rebase master # Reapply commits on the top of the master branch.
git push -f # Update your remote branch with the local changes.

NOTE: When you use the git push-f command, make sure you do not work on a branch simultaneously with another person.

  1. Merge your pull request.

Use GitHub to merge the pull request. If you are an external contributor, contact the repository maintainers specified in the CODEOWNERS file to do the merge.

NOTE: If there are at least two contributors who add commits to the pull request, contact the repository administrators to enable the Rebase and merge option temporarily. It allows you to merge the pull request with the number of commits that corresponds to the number of its contributors.

Keep your branch up to date

Perform these actions if you work on a branch for a long period of time and you want to update it locally with changes from the upstream repository.

Systematically incorporate changes from the master branch into your branch. To keep your branch up to date, use the git rebase master command as described in the following flow:

Click to copy
git checkout master # Switch to the master branch.
git pull # Update the master branch by pulling all changes.
git checkout {branch-name} # Switch back to your branch.
git rebase master # Reapply commits on the top of the master branch.

See how to rebase the master branch step-by-step in this video:

Rebase

NOTE: Do not merge the master branch into another branch as it can make latter rebase not feasible.