Repository
Overview
Repository guidelines include:
- The instruction that lists recommended settings for a new repository in the
kyma-project
andkyma-incubator
organizations. - The content description of the
repository-template
folder that provides the structure of an exemplary Kyma repository. Use it whenever you create a new repository within Kyma.
New repository settings
All repositories in kyma-project
and kyma-incubator
organizations should be similar in structure, settings, and restrictions. Follow these guidelines to adjust settings of a new repository created in one of these organizations.
NOTE: You have to be an owner of the given organization to create a new repository in it.
Use the repository template
After you create a new repository, copy the basic repository structure from the template
folder that is available in the community
repository. It contains such files as the obligatory Apache license, the CODEOWNERS
file that governs the review and approval flow in the repository, and the Stale Bot that handles inactive issues.
After copying the folder's contents, modify these according to the instructions they contain:
CODEOWNERS
to define who is responsible for the review and approval of specific repository partsREADME.md
to describe the repository and explain how to use and develop it
Adjust repository options
Under the repository name, choose the Settings tab. The Options view opens as the default one in the left menu.
- Scroll down to the Features section and clear these options:
- Wikis
- Restrict editing to users in teams with push access only
- Projects
- Go to the Merge button section and clear these options:
- Allow merge commits
- Allow rebase merging
Leave only the Allow squash merging option selected. This option combines all commits into one before merging the changes into the master
branch.
Set branch protection rules
Define branch protection rules that include enforcing obligatory review and approval of pull requests (PRs), and define which Prow jobs need to pass successfully before merging PR changes into the master
branch.
To see these settings, go to Branches in the left menu, under repository Settings:
In Kyma, the protection rules are defined in the Prow config.yaml
file generated from rules defined in the prow-config.yaml
file and handled by a Prow component called Branch Protector.
If you add a new repository in:
kyma-project
, you do not need to add a new entry to the Prowconfig.yaml
file as the branch protection is already defined for all repositories within this organization. The only exception is if you want to specify additional rules that are not handled by Prow.kyma-incubator
, add a new repository entry to the Prowconfig.yaml
file, under branch-protection.orgs.kyma-incubator.repos. See an example of such an entry for themarketplaces
repository.
Add webhooks
Add ZenHub and Prow webhooks to integrate them with your repository. This way, GitHub can send all events from the repository to Prow and notify ZenHub on the selected events related to issues and pull requests.
These settings are available under Webhooks in the left menu, under repository Settings:
Prow webhook
Only Prow admins can activate the Prow webhook. To activate the Prow webhook in your repository, a Prow admin must have admin permissions. Contact Prow admins by creating an issue in the test-infra
repository with the details of your request. You can also contact them on the CI Slack channel.
To activate the Prow webook:
1. A Prow admin connects to the Prow cluster and retrieves hmac-token
from a Secret. They run:
kubectl get secret hmac-token -o jsonpath="{.data.hmac}" | base64 --decode
- The Prow admin enters the
hmac-token
into the Secret field.
ZenHub webhook
To activate the ZenHub webhook: 1. Go to the Kyma workspace on ZenHub. 2. Click Repos and select the Add Repos option.
- Choose the organization in the left bottom corner of the pop-up box, select the repository you want to add from the available list, and click the Add this repo button.
Update CLA assistant configuration
Ask a kyma-project owner to add the newly created repository to the Contributor License Agreement (CLA).
Add a milv file
If you define any governance-related Prow job for the new repository to validate documentation links, you must add a milv.config.yaml
file at the root of the repository. See an example of the milv file.
Create labels
Define labels for the new repository so you could use them in issues and pull requests. Follow the naming convention and color array used in other repositories such as kyma
.
TIP: You can copy labels from the existing repository to the new repository using the GitHub CLI tool.
Add the repository to teams
Add the repository to both developers and developers-triage teams.
Repository template
The repository-template
folder offers a unified file, document, and folder structure. Use it for every new repository that you create in Kyma. It helps you to ensure that the project is consistent and standardized.
Usage
The repository-template
folder contains all elements required for a skeleton repository. However, before you copy the content of the repository-template
folder into your new repository, read carefully the following paragraph to learn what the purpose of the specific files and documents is and which of them you need to adjust.
The repository-template
folder consists of:
.github
- This folder contains the pull request template, issue templates, and the Stale Bot that monitors inactive issues, marks them asstale
, and closes them after the specified period of time.docs
- In this folder, put the repository-specific documentation only. Store any architectural decisions or documents applicable to all Kyma repositories in thecommunity
repository.CODE_OF_CONDUCT.md - This document is a ready-to-use template which provides a link to the general
CODE_OF_CONDUCT.md
document from thecommunity
repository. Copy the template into your own repository.CODEOWNERS - In this document, specify the owners of particular parts of your repository. The owners are automatically added as reviewers when you open a pull request that modifies the code and content they own. If you additionally modify the settings of the master branch and select the Require review from Code Owners option, their approvals become obligatory to merge the pull request. Configure the
CODEOWNERS
document and adjust your master branch. TheCODEOWNERS
document contains instructions on how to do both properly.CONTRIBUTING.md - This template makes a reference to the
CONTRIBUTING.md
document that contains the general guidance from thecommunity
repository and describes the rules for contributing to all Kyma repositories. If there is any additional, project-specific information that you want to add to your project'sCONTRIBUTING.md
document, add them under the same sections as in the generalCONTRIBUTING.md
document.LICENSE - It is an obligatory element of every open-source repository. Copy the template into your repository.
NOTICE.md - The document defines the ownership of the copyright in the repository. Copy the template into your repository.
README.md - This is a template with sections that you fill in according to the provided suggestions. Add any information specific for a development guide in this document. Describe how your project works, how to use it, and how to develop it. Because all sections are optional, remove those that do not apply to your project.