kubevela/CONTRIBUTING.md

CONTRIBUTING Guide

About KubeVela

KubeVela project is initialized and maintained by the cloud native community since day 0 with bootstrapping contributors from 8+ different organizations. We intend for KubeVela to have an open governance since the very beginning and donate the project to neutral foundation as soon as it's released.

This doc explains how to set up a development environment, so you can get started contributing to kubevela or build a PoC (Proof of Concept).

Development

Prerequisites

1. Golang version 1.16+
2. Kubernetes version v1.16+ with ~/.kube/config configured.
3. ginkgo 1.14.0+ (just for E2E test)
4. golangci-lint 1.31.0+, it will install automatically if you run make, you can install it manually if the installation is too slow.
5. kubebuilder v2.3.0+

Install Kubebuilder manually

linux:

wget https://github.com/kubernetes-sigs/kubebuilder/releases/download/v2.3.1/kubebuilder_2.3.1_linux_amd64.tar.gz
tar -zxvf  kubebuilder_2.3.1_linux_amd64.tar.gz
mkdir -p /usr/local/kubebuilder/bin
sudo mv kubebuilder_2.3.1_linux_amd64/bin/* /usr/local/kubebuilder/bin

macOS:

wget https://github.com/kubernetes-sigs/kubebuilder/releases/download/v2.3.1/kubebuilder_2.3.1_darwin_amd64.tar.gz
tar -zxvf  kubebuilder_2.3.1_darwin_amd64.tar.gz
mkdir -p /usr/local/kubebuilder/bin
sudo mv kubebuilder_2.3.1_darwin_amd64/bin/* /usr/local/kubebuilder/bin

We also recommend you to learn about KubeVela's design before diving into its code.

Build

• Clone this project

git clone git@github.com:oam-dev/kubevela.git

KubeVela includes two parts, vela core and vela cli.

• The vela core is actually a K8s controller, it will watch OAM Spec CRD and deploy resources.
• The vela cli is a command line tool that can build, run apps(with the help of vela core).

For local development, we probably need to build both of them.

• Build Vela CLI

make

After the vela cli built successfully, make command will create vela binary to bin/ under the project.

• Configure vela binary to System PATH

export PATH=$PATH:/your/path/to/project/kubevela/bin

Then you can use vela command directly.

• Build Vela Core

make manager

• Run Vela Core

Firstly make sure your cluster has CRDs, below is the command that can help install all CRDs.

make core-install

Run locally:

make core-run

This command will run controller locally, it will use your local KubeConfig which means you need to have a k8s cluster locally. If you don't have a one, we suggest that you could setup up a cluster with kind.

When you're developing vela-core, make sure the controller installed by helm chart is not running. Otherwise, it will conflict with your local running controller.

You can check and uninstall it by using helm.

helm list -A
helm uninstall -n vela-system kubevela

Use

You can try use your local built binaries follow the documentation.

Testing

Unit test

make test

E2E test

Before e2e test start, make sure you have vela-core running.

make core-run

Start to test.

make e2e-test

Logging Conventions

Structured logging

We recommend using klog.InfoS to structure the log. The msg argument need start from a capital letter. and name arguments should always use lowerCamelCase.

// func InfoS(msg string, keysAndValues ...interface{})
klog.InfoS("Reconcile traitDefinition", "traitDefinition", klog.KRef(req.Namespace, req.Name))
// output:
// I0605 10:10:57.308074   22276 traitdefinition_controller.go:59] "Reconcile traitDefinition" traitDefinition="vela-system/expose"

Use klog.KObj and klog.KRef for Kubernetes objects

klog.KObj and klog.KRef can unify the output of kubernetes object.

// KObj is used to create ObjectRef when logging information about Kubernetes objects
klog.InfoS("Start to reconcile", "appDeployment", klog.KObj(appDeployment))
// KRef is used to create ObjectRef when logging information about Kubernetes objects without access to metav1.Object
klog.InfoS("Reconcile application", "application", klog.KRef(req.Namespace, req.Name))

Logging Level

This file contains KubeVela's log level, you can set the log level by klog.V(level).

// you can use klog.V(common.LogDebug) to print debug log
klog.V(common.LogDebug).InfoS("Successfully applied components", "workloads", len(workloads))

more detail in Structured Logging Guide.

Contribute Docs

Please read the documentation before contributing to the docs.

• Build docs

make docs-build

• Local development and preview

make docs-start

Make a pull request

Remember to write unit-test and e2e-test after you have finished your code.

Run following checks before making a pull request.

make reviewable

The command will do some lint checks and clean code.

After that, check in all changes and send a pull request.

Merge Regulations

Before merging, the pull request should obey the following rules:

• The commit title and message should be clear about what this PR does.
• All test CI should pass green.
• The codecov/project should pass. This means the coverage should not drop. See Codecov commit status.