提交 5c3834ac 编写于 作者: C Calvin Yu

first draft of project initial files

上级 2a6b79d6
DATA_PATH=./tmp
KUBESPHERE_LOG_LEVEL=debug
pkg/cmd/api/spec/api.swagger.json linguist-generated=true
pkg/cmd/api/spec/static.go linguist-generated=true
# Binaries for programs and plugins
*.exe
*.exe~
*.dll
*.so
*.dylib
# Test binary, build with `go test -c`
*.test
# Output of the go coverage tool, specifically when used with LiteIDE
*.out
.idea
bin/
.vscode/
tmp/
sudo: required
services:
- docker
language: go
go:
- 1.9
- tip
go_import_path: kubesphere.io/kubesphere
before_install:
- curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
- sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"
- sudo apt-get update
- sudo apt-get -y install docker-ce
before_script:
- docker --version
script:
- make fmt-check
- make ci-test
# This is the official list of KubeSphere authors for copyright purposes.
# This file is distinct from the CONTRIBUTORS files.
# See the latter for an explanation.
# Names should be added to this file as one of
# Organization's name
# Individual's name <submission email address>
# Individual's name <submission email address> <email2> <emailN>
# See CONTRIBUTORS for the meaning of multiple email addresses.
# Please keep the list sorted.
Yunify Inc.
# This is the official list of people who can contribute
# (and typically have contributed) code to the KubeSphere repository.
# The AUTHORS file lists the copyright holders; this file
# lists people. For example, Yunify employees are listed here
# but not in AUTHORS, because Yunify holds the copyright.
#
# When adding J Random Contributor's name to this file,
# either J's name or J's organization's name should be
# added to the AUTHORS file.
# Names should be added to this file like so:
# Individual's name <submission email address>
# Individual's name <submission email address> <email2> <emailN>
#
# An entry with multiple email addresses specifies that the
# first address should be used in the submit logs.
# Please keep the list sorted.
Ray@qingcloud <ray@yunify.com>
\ No newline at end of file
# Copyright 2018 The KubeSphere Authors. All rights reserved.
# Use of this source code is governed by a Apache license
# that can be found in the LICENSE file.
FROM kubesphere/kubesphere-builder as builder
WORKDIR /go/src/kubesphere.io/kubesphere/
COPY . .
RUN go generate kubesphere.io/kubesphere/pkg/version && \
go install kubesphere.io/kubesphere/cmd/...
FROM alpine:3.6
RUN apk add --update ca-certificates && update-ca-certificates
COPY --from=builder /go/bin/* /usr/local/bin/
CMD ["sh"]
FROM alpine:3.6
RUN apk add --update ca-certificates && update-ca-certificates
COPY ./* /usr/local/bin/
CMD ["sh"]
# Copyright 2018 The KubeSphere Authors. All rights reserved.
# Use of this source code is governed by a Apache license
# that can be found in the LICENSE file.
TARG.Name:=kubesphere
TRAG.Gopkg:=kubesphere.io/kubesphere
TRAG.Version:=$(TRAG.Gopkg)/pkg/version
DOCKER_TAGS=latest
RUN_IN_DOCKER:=docker run -it -v `pwd`:/go/src/$(TRAG.Gopkg) -v `pwd`/tmp/cache:/root/.cache/go-build -w /go/src/$(TRAG.Gopkg) -e GOBIN=/go/src/$(TRAG.Gopkg)/tmp/bin -e USER_ID=`id -u` -e GROUP_ID=`id -g` kubesphere/kubesphere-builder
GO_FMT:=goimports -l -w -e -local=kubesphere -srcdir=/go/src/$(TRAG.Gopkg)
GO_FILES:=./cmd ./test ./pkg
define get_diff_files
$(eval DIFF_FILES=$(shell git diff --name-only --diff-filter=ad | grep -E "^(test|cmd|pkg)/.+\.go"))
endef
define get_build_flags
$(eval SHORT_VERSION=$(shell git describe --tags --always --dirty="-dev"))
$(eval SHA1_VERSION=$(shell git show --quiet --pretty=format:%H))
$(eval DATE=$(shell date +'%Y-%m-%dT%H:%M:%S'))
$(eval BUILD_FLAG= -X $(TRAG.Version).ShortVersion="$(SHORT_VERSION)" \
-X $(TRAG.Version).GitSha1Version="$(SHA1_VERSION)" \
-X $(TRAG.Version).BuildDate="$(DATE)")
endef
.PHONY: all
all: generate build
.PHONY: help
help:
# TODO: update help info to last version
@echo "TODO"
.PHONY: init-vendor
init-vendor:
@if [[ ! -f "$$(which govendor)" ]]; then \
go get -u github.com/kardianos/govendor; \
fi
govendor init
govendor add +external
@echo "init-vendor done"
.PHONY: update-vendor
update-vendor:
@if [[ ! -f "$$(which govendor)" ]]; then \
go get -u github.com/kardianos/govendor; \
fi
govendor update +external
govendor list
@echo "update-vendor done"
.PHONY: update-builder
update-builder:
docker pull kubesphere/kubesphere-builder
@echo "update-builder done"
.PHONY: generate-in-local
generate-in-local:
cd ./api && make generate
cd ./pkg/cmd/api && make
go generate ./pkg/version/
.PHONY: generate
generate:
$(RUN_IN_DOCKER) make generate-in-local
@echo "generate done"
.PHONY: fmt-all
fmt-all:
$(RUN_IN_DOCKER) $(GO_FMT) $(GO_FILES)
@echo "fmt done"
.PHONY: fmt
fmt:
$(call get_diff_files)
$(if $(DIFF_FILES), \
$(RUN_IN_DOCKER) $(GO_FMT) ${DIFF_FILES}, \
$(info cannot find modified files from git) \
)
@echo "fmt done"
.PHONY: fmt-check
fmt-check: fmt-all
$(call get_diff_files)
$(if $(DIFF_FILES), \
exit 2 \
)
.PHONY: build
build: fmt
mkdir -p ./tmp/bin
$(call get_build_flags)
$(RUN_IN_DOCKER) time go install -ldflags '$(BUILD_FLAG)' $(TRAG.Gopkg)/cmd/...
@docker build -t $(TARG.Name) -f ./Dockerfile.dev ./tmp/bin
@docker image prune -f 1>/dev/null 2>&1
@echo "build done"
.PHONY: compose-update
compose-update: build compose-up
@echo "compose-update done"
.PHONY: compose-update-service-without-deps
compose-update-service-without-deps: build
docker-compose up -d --no-dep $(COMPOSE_APP_SERVICES)
@echo "compose-update-service-without-deps done"
.PHONY: compose-logs-f
compose-logs-f:
docker-compose logs -f $(COMPOSE_APP_SERVICES)
compose-update-%:
docker-compose up -d --no-deps $*
@echo "compose-update done"
.PHONY: compose-up
compose-up:
docker-compose up -d
@echo "compose-up done"
.PHONY: compose-down
compose-down:
docker-compose down
@echo "compose-down done"
.PHONY: release
release:
@echo "TODO"
.PHONY: test
test:
@make unit-test
@make e2e-test
@echo "test done"
.PHONY: e2e-test
e2e-test:
go test -v ./test/...
@echo "e2e-test done"
.PHONY: ci-test
ci-test:
# build with production Dockerfile, not dev version
@docker build -t $(TARG.Name) -f ./Dockerfile .
@make compose-up
#sleep 20
#@make unit-test
#@make e2e-test
#@echo "ci-test done"
.PHONY: clean
clean:
-make -C ./pkg/version clean
@echo "ok"
.PHONY: unit-test
unit-test:
@echo "unit-test done"
# kubesphere
\ No newline at end of file
# KubeSphere
[![License](http://img.shields.io/badge/license-apache%20v2-blue.svg)](https://github.com/KubeSphere/KubeSphere/blob/master/LICENSE)
----
***KubeSphere*** is a distribution of [Kubernetes](https://kubernetes.io), aimed to provide quiick setup, friendly and easily use, and powerful management features for Kubernetes clusters, which could help both personal and enterprise users, reduce their learning curve of Kubernetes, accelerate their transform process from other container platforms to Kubernetes.
**Features:**
TBD
----
## Motivation
The project originates from the requirement and pains we heard from our customers on public and private QingCloud platform, who have strong will to deploy Kubernetes in their IT system but struggle on completed setup process and long learning curve. With help of KubeSphere, their IT operators could setup Kubernetes environment quickly and use an easy management UI interface to mange their applications.
Getting Started
---------------
**TBD**
## Design
## Contributing to the project
All [members](docs/members.md) of the KubeSphere community must abide by the [CNCF Code of Conduct](https://github.com/cncf/foundation/blob/master/code-of-conduct.md). Only by respecting each other can we develop a productive, collaborative community.
You can then check out how to [setup for development](docs/development.md).
# Copyright 2018 The KubeSphere Authors. All rights reserved.
# Use of this source code is governed by a Apache license
# that can be found in the LICENSE file.
FROM golang:1.10.1-alpine3.7 as builder
RUN apk add --no-cache git curl openssl
RUN go get github.com/golang/protobuf/protoc-gen-go
RUN go get github.com/grpc-ecosystem/grpc-gateway/protoc-gen-grpc-gateway
RUN go get github.com/grpc-ecosystem/grpc-gateway/protoc-gen-swagger
RUN go get github.com/chai2010/protorpc/protoc-gen-stdrpc
RUN go get golang.org/x/tools/cmd/goimports
# swagger-0.13.0
# RUN go get github.com/go-swagger/go-swagger/cmd/swagger
RUN mkdir -p /swagger && cd /swagger \
&& wget https://github.com/go-swagger/go-swagger/releases/download/0.13.0/swagger_linux_amd64 \
&& chmod +x swagger_linux_amd64 && mv swagger_linux_amd64 /go/bin/swagger
# the protoc can't run on alpine,
# we only need the protobuf's stdarnd library in the `/protoc/include`.
RUN mkdir -p /protoc && cd /protoc \
&& wget https://github.com/google/protobuf/releases/download/v3.5.0/protoc-3.5.0-linux-x86_64.zip \
&& unzip protoc-3.5.0-linux-x86_64.zip
FROM golang:1.10.1-alpine3.7
RUN apk add --no-cache git protobuf make curl openssl jq rsync
COPY --from=builder /protoc/include /usr/local/include
COPY --from=builder /go/bin /go/bin
# Copyright 2018 The KubeSphere Authors. All rights reserved.
# Use of this source code is governed by a Apache license
# that can be found in the LICENSE file.
default:
docker build -t kubesphere/kubesphere-builder .
@echo "ok"
pull:
docker pull kubesphere/kubesphere-builder
@echo "ok"
run:
docker run --rm -it -v `pwd`:/root kubesphere/kubesphere-builder
clean:
@echo "ok"
// Copyright 2017 The OpenPitrix Authors. All rights reserved.
// Use of this source code is governed by a Apache license
// that can be found in the LICENSE file.
// Package openpitrix provides the best Paas and Iaas platform.
package kubesphere
# Copyright 2018 The KubeSphere Authors. All rights reserved.
# Use of this source code is governed by a Apache license
# that can be found in the LICENSE file.
# OpenPitrix Developer Guide
The developer guide is for anyone wanting to either write code which directly accesses the
OpenPitrix API, or to contribute directly to the OpenPitrix project.
## The process of developing and contributing code to the OpenPitrix project
* **Welcome to OpenPitrix (New Developer Guide)**
([welcome-to-OpenPitrix-new-developer-guide.md](welcome-to-OpenPitrix-new-developer-guide.md)):
An introductory guide to contributing to OpenPitrix.
* **On Collaborative Development** ([collab.md](collab.md)): Info on pull requests and code reviews.
* **GitHub Issues** ([issues.md](issues.md)): How incoming issues are triaged.
* **Pull Request Process** ([pull-requests.md](pull-requests.md)): When and why pull requests are closed.
* **Getting Recent Builds** ([getting-builds.md](getting-builds.md)): How to get recent builds including the latest builds that pass CI.
* **Automated Tools** ([automation.md](automation.md)): Descriptions of the automation that is running on our github repository.
## Setting up your dev environment, coding, and debugging
* **Development Guide** ([development.md](development.md)): Setting up your development environment.
* **Testing** ([testing.md](testing.md)): How to run unit, integration, and end-to-end tests in your development sandbox.
* **Hunting flaky tests** ([flaky-tests.md](flaky-tests.md)): We have a goal of 99.9% flake free tests.
Here's how to run your tests many times.
* **Logging Conventions** ([logging.md](logging.md)): Glog levels.
* **Coding Conventions** ([coding-conventions.md](coding-conventions.md)):
Coding style advice for contributors.
* **Document Conventions** ([how-to-doc.md](how-to-doc.md))
Document style advice for contributors.
* **Running a cluster locally** ([running-locally.md](running-locally.md)):
A fast and lightweight local cluster deployment for development.
## Developing against the OpenPitrix API
* The [REST API documentation](http://openpitrix.io/docs/reference/) explains the REST
API exposed by apiserver.
## Building releases
See the [openpitrix/release](https://github.com/kubernetes/release) repository for details on creating releases and related tools and helper scripts.
# Architecture
Basic idea is to decouple application repository and runtime environment. The runtime environment an application can run is by matching the labels of runtime environment and the selector of the repository where the application is from.
## Design key points:
// Copyright 2017 The OpenPitrix Authors. All rights reserved.
// Use of this source code is governed by a Apache license
// that can be found in the LICENSE file.
// dot -Tpng -o output.png input.dot
digraph G {
rankdir = LR;
subgraph clusterClient {
node [
fixedsize = true,
width = 1, height = 1,
]
WebUI [shape = doublecircle];
MobileApp [shape = doublecircle];
XClient [shape = doublecircle];
}
WebUI -> ApiGateway[
label = "rest api",
dir = both,
style = bold,
];
MobileApp -> ApiGateway[
label = "rest api",
dir = both,
style = bold,
];
XClient -> ApiGateway[
label = "rest api",
dir = both,
style = bold,
];
subgraph clusterOpenpitrix {
// rest api gateway
ApiGateway [shape = rect,
fixedsize = true,
width = 1.4, height = 6.2,
];
// microservice
subgraph clusterServices {
node [
shape=record,
fixedsize = true,
width = 2.6, height = 1.3,
];
Cluster [shape = Mrecord];
Runtime [shape = Mrecord,
label="Runtime |{ plugin |{k8s|QingCloud|Other} }"
];
App [shape = Mrecord];
Repo [shape = Mrecord];
}
// service database
subgraph clusterDB {
node [
fixedsize = true,
width = 2.6, height = 1.3,
];
RepoDB [shape = cylinder];
AppDB [shape = cylinder];
RuntimeDB [shape = cylinder];
ClusterDB [shape = cylinder];
}
// api gateway
ApiGateway -> Cluster [
label = "grpc",
dir = both,
style = bold,
];
ApiGateway -> Repo [
label = "grpc",
dir = both,
style = bold,
];
ApiGateway -> App [
label = "grpc",
dir = both,
style = bold,
];
ApiGateway -> Runtime [
label = "grpc",
dir = both,
style = bold,
];
Repo -> RepoDB [label="SQL"];
App -> AppDB [label="SQL"];
Runtime -> RuntimeDB [label="SQL"];
Cluster -> ClusterDB [label="SQL"];
}
}
# Developing for KubeSphere
The [community repository](https://github.com/kubesphere) hosts all information about
building KubeSphere from source, how to contribute code and documentation, who to contact about what, etc. If you find a requirement that this doc does not capture, or if you find other docs with references to requirements that are not simply links to this doc, please [submit an issue](https://github.com/kubesphere/kubesphere/issues/new).
----
## To start developing KubeSphere
First of all, you should fork the project. Then follow one of the three options below to develop the project. Please note you should replace the official repo when using __go get__ or __git clone__ below with your own one.
### 1. You have a working [Docker Compose](https://docs.docker.com/compose/install) environment [recommend].
>You need to install [Docker](https://docs.docker.com/engine/installation/) first.
```shell
$ git clone https://github.com/kubesphere/kubesphere
$ cd kubesphere
$ make build
$ make compose-up
```
Exit docker runtime environment
```shell
$ make compose-down
```
### 2. You have a working [Docker](https://docs.docker.com/engine/installation/) environment.
Exit docker runtime environment
```shell
$ docker stop $(docker ps -f name=kubesphere -q)
```
### 3. You have a working [Go](prereqs.md#setting-up-go) environment.
- Install [protoc compiler](https://github.com/google/protobuf/releases/)
- Install protoc plugin:
```shell
$ go get github.com/golang/protobuf/protoc-gen-go
$ go get github.com/grpc-ecosystem/grpc-gateway/protoc-gen-grpc-gateway
$ go get github.com/grpc-ecosystem/grpc-gateway/protoc-gen-swagger
$ go get github.com/mwitkow/go-proto-validators/protoc-gen-govalidators
```
- Get kubesphere source code and build service:
```shell
$ go get -d kubesphere.io/kubesphere
$ cd $GOPATH/src/kubesphere.io/kubesphere
$ make generate
$ GOBIN=`pwd`/bin go install ./cmd/...
```
- Start KubeSphere service:
- Exit go runtime environment
```shell
$ ps aux | grep kubesphere- | grep -v grep | awk '{print $2}' | xargs kill -9
```
----
## Test KubeSphere
Visit http://127.0.0.1:9100/swagger-ui in browser, and try it online, or test kubesphere api service via command line:
----
## DevOps
Please check [How to set up DevOps environment](devops.md).
# Set Up DevOps Environment
DevOps is recommended to use for this project. Please follow the instructions below to set up your environment. We use Jenkins with Blue Ocean plugin and deploy it on Kubernetes, also continuously deploy KubeSphere on the Kubernetes cluster.
----
- [Create Kubernetes Cluster](#create-kubernetes-cluster)
- [Deploy Jenkins](#deploy-jenkins)
- [Configure Jenkins](#configure-jenkins)
- [Create a Pipeline](#create-a-pipeline)
## Create Kubernetes Cluster
We are using [Kubernetes on QingCloud](https://appcenter.qingcloud.com/apps/app-u0llx5j8) to create a kubernetes production environment by one click. Please follow the [instructions](https://appcenter-docs.qingcloud.com/user-guide/apps/docs/kubernetes/) to create your own cluster. Access the Kubernetes client using one of the following options.
- **Open VPN**<a id="openvpn"></a>: Go to the left navigation tree of the [QingCloud console](https://console.qingcloud.com), choose _Networks & CDN_, then _VPC Networks_; on the content of the VPC page, choose _Management Configuration_, _VPN Service_, then you will find _Open VPN_ service. Here is the [screenshot](images/openvpn.png) of the page.
- **Port Forwarding**<a id="port-forwarding"></a>: same as Open VPN, but choose _Port Forwarding_ on the content of VPC page instead of VPN Service; and add a rule to forward source port to the port of ssh port of the kubernetes client, for instance, forward 10007 to 22 of the kubernetes client with the private IP being 192.168.100.7. After that, you need to open the firewall to allow the port 10007 accessible from outside. Please click the _Security Group_ ID on the same page of the VPC, and add the downstream rule for the firewall.
- **VNC**: If you don't want to access the client node remotely, just go to the kubernetes cluster detailed page on the [QingCloud console](https://console.qingcloud.com), and click the windows icon aside of the client ID shown as the [screenshot](images/kubernets.png) (user/password: root/k8s). The way is not recommended, however you can check kubernetes quickly using VNC since you don't configure anything.
## Deploy Jenkins
1. Copy the [yaml file](../devops/kubernetes/jenkins-qingcloud.yaml) to the kubernetes client, and deploy
```
# kubectl apply -f jenkins-qingcloud.yaml
```
2. Access Jenkins console by opening http://\<ip\>:9200 where ip depends on how you expose the Jenkins service to outside explained below. (You can find your way to access Jenkins console such as ingress, cloud LB etc.) On the kubernetes client
```
# iptables -t nat -A PREROUTING -p tcp -i eth0 --dport 9200 -j DNAT --to-destination "$(kubectl get svc -n jenkins --selector=app=jenkins -o jsonpath='{.items..spec.clusterIP}')":9200
# iptables -t nat -A POSTROUTING -p tcp --dport 9200 -j MASQUERADE
# sysctl -w net.ipv4.conf.eth0.route_localnet=1
```
3. Now the request to the kubernetes client port 9200 will be forwarded to the Jenkins service.
- If you use [Open VPN](#openvpn) to access the kubernetes client, then open http://\<kubernetes client private ip\>:9200 to access Jenkins console.
- If you use [Port Forwarding](#port-forwarding) to access the client, then forward the VPC port 9200 to the kubernetes client port 9200. Now open http://\<VPC EIP\>:9200 to access Jenkins console.
## Configure Jenkins
> You can refer [jenkins.io](https://jenkins.io/doc/tutorials/using-jenkins-to-build-a-java-maven-project/) about how to configure Jenkins and create a pipeline.
1. Unlock Jenkins
- Get the Adminstrator password from the log on the kubernetes client
```
# kubectl logs "$(kubectl get pods -n jenkins --selector=app=jenkins -o jsonpath='{.items..metadata.name}')" -c jenkins -n jenkins
```
- Go to Jenkins console, paste the password and continue. Install suggested plugins, then create the first admin user and save & finish.
2. Configure Jenkins
We will deploy KubeSphere application into the same Kubernetes cluster as the one that the Jenkins is running on. So we need configure the Jenkins pod to access the Kubernetes cluster, and log in docker registry given that during the [Jenkins pipeline](#create-a-pipeline) we push KubeSphere image into a registry which you can change on your own.
On the Kubernetes client, execute the following to log in Jenkins container.
```
# kubectl exec -it "$(kubectl get pods -n jenkins --selector=app=jenkins -o jsonpath='{.items..metadata.name}')" -c jenkins -n jenkins -- /bin/bash
```
After logging in the Jenkins container, then run the following to log in docker registry and prepare folder to hold kubectl configuration.
```
bash-4.3# docker login -u xxx -p xxxx
bash-4.3# mkdir /root/.kube
bash-4.3# exit
```
Once back again to the Kubernetes client, run the following to copy the tool kubectl and its configuration from the client to the Jenkins container.
```
# kubectl cp /usr/bin/kubectl jenkins/"$(kubectl get pods -n jenkins --selector=app=jenkins -o jsonpath='{.items..metadata.name}')":/usr/bin/kubectl -c jenkins
# kubectl cp /root/.kube/config jenkins/"$(kubectl get pods -n jenkins --selector=app=jenkins -o jsonpath='{.items..metadata.name}')":/root/.kube/config -c jenkins
```
## Create a pipeline
- Fork KubeSphere from github for your development. You need to change the docker repository to your own in the files [kubesphere.yaml](devops/kubernetes/kubesphere.yaml), [build-images.sh](devops/scripts/build-images.sh), [push-images.sh](devops/scripts/push-images.sh) and [clean.sh](devops/scripts/clean.sh).
- On the Jenkins panel, click _Open Blue Ocean_ and start to create a new pipeline. Choose _GitHub_, paste your access key of GitHub, select the repository you want to create a CI/CD pipeline. We already created the pipeline Jenkinsfile on the upstream repository which includes compiling KubeSphere, building images, push images, deploying the application, verifying the application and cleaning up.
- It is better to configure one more thing. On the Jenkins panel, go to the configuration of KubeSphere, check _Periodically if not otherwise run_ under _Scan Repository Triggers_ and select the interval at your will.
- If your repository is an upstream, you can select _Discover pull requests from forks_ under _Behaviors_ so that the pipeline will work for PR before merged.
- Now it is good to go. Whenever you commit a change to your forked repository, the pipeline will work during the Jenkins trigger interval.
# Contributors
## Component and Member List
| Name | Leads |
|------|-------|
| Deployment | (yunify) |
| Service | (yunify) |
| Application | (yunify) |
| Cluster | Jeff (yunify) |
| App Runtime | (yunify) |
| Documents | |
# Developing for KubeSphere [deprecated]
This document is intended to be the canonical source of truth for things like
supported toolchain versions for building KubeSphere.
If you find a requirement that this doc does not capture, or if you find other
docs with references to requirements that are not simply links to this doc,
please [submit an issue](https://github.com/kubesphere/kubesphere/issues/new).
This document is intended to be relative to the branch in which it is found.
It is guaranteed that requirements will change over time for the development
branch, but release branches should not change.
- [Prerequisites](#prerequisites)
- [Setting up Go](#setting-up-go)
- [Setting up Swagger](#setting-up-swagger)
- [To start developing KubeSphere](#to-start-developing-kubesphere)
- [DevOps](#devops)
## Prerequisites
KubeSphere only has few external dependencies you need to setup before being
able to build and run the code.
### Setting up Go
KubeSphere written in the [Go](http://golang.org) programming language.
To build, you'll need a Go (version 1.9+) development environment.
If you haven't set up a Go development environment, please follow
[these instructions](https://golang.org/doc/install)
to install the Go tools.
Set up your GOPATH and add a path entry for Go binaries to your PATH. Typically
added to your ~/.profile:
```shell
$ export GOPATH=~/go
$ export PATH=$PATH:$GOPATH/bin
```
### Setting up Swagger
KubeSphere is using [OpenAPI/Swagger](https://swagger.io) to develop API, so follow
[the instructions](https://github.com/go-swagger/go-swagger/tree/master/docs) to
install Swagger. If you are not familar with Swagger, please read the
[tutorial](http://apihandyman.io/writing-openapi-swagger-specification-tutorial-part-1-introduction/#writing-openapi-fka-swagger-specification-tutorial). If you install Swagger using docker distribution,
please run
```shell
$ docker pull quay.io/goswagger/swagger
$ alias swagger="docker run --rm -it -e GOPATH=$GOPATH:/go -v $HOME:$HOME -w $(pwd) quay.io/goswagger/swagger"
$ swagger version
```
## To start developing KubeSphere
There are two options to get KubeSphere source code and build the project:
**You have a working Go environment.**
```shell
$ go get -d kubesphere.io/kubesphere
$ cd $GOPATH/src/kubesphere.io/kubesphere
$ make all
```
**You have a working Docker environment.**
```shell
$ git clone https://github.com/kubesphere/kubesphere
$ cd kubesphere
$ make
```
## DevOps
Please check [How to set up DevOps environment](devops.md)
# Pull Request Process
This doc explains the process and best practices for submitting a PR to the [KubeSphere project](https://github.com/kubeSphere/kubeSphere). It should serve as a reference for all contributors, and be useful especially to new and infrequent submitters.
- [Before You Submit a PR](#before-you-submit-a-pr)
* [Run Local Verifications](#run-local-verifications)
* [Sign the CLA](#sign-the-cla)
- [The PR Submit Process](#the-pr-submit-process)
* [Write Release Notes if Needed](#write-release-notes-if-needed)
* [The Testing and Merge Workflow](#the-testing-and-merge-workflow)
* [Marking Unfinished Pull Requests](#marking-unfinished-pull-requests)
* [Comment Commands Reference](#comment-commands-reference)
* [Automation](#automation)
* [How the e2e Tests Work](#how-the-e2e-tests-work)
- [Why was my PR closed?](#why-was-my-pr-closed)
- [Why is my PR not getting reviewed?](#why-is-my-pr-not-getting-reviewed)
- [Best Practices for Faster Reviews](#best-practices-for-faster-reviews)
* [0. Familiarize yourself with project conventions](#0-familiarize-yourself-with-project-conventions)
* [1. Is the feature wanted? Make a Design Doc or Sketch PR](#1-is-the-feature-wanted-make-a-design-doc-or-sketch-pr)
* [2. Smaller Is Better: Small Commits, Small PRs](#2-smaller-is-better-small-commits-small-prs)
* [3. Open a Different PR for Fixes and Generic Features](#3-open-a-different-pr-for-fixes-and-generic-features)
* [4. Comments Matter](#4-comments-matter)
* [5. Test](#5-test)
* [6. Squashing and Commit Titles](#6-squashing-and-commit-titles)
* [7. KISS, YAGNI, MVP, etc.](#7-kiss-yagni-mvp-etc)
* [8. It's OK to Push Back](#8-its-ok-to-push-back)
* [9. Common Sense and Courtesy](#9-common-sense-and-courtesy)
# Before You Submit a PR
This guide is for contributors who already have a PR to submit. If you're looking for information on setting up your developer environment and creating code to contribute to KubeSphere, see the [development guide](development.md).
**Make sure your PR adheres to our best practices. These include following project conventions, making small PRs, and commenting thoroughly. Please read the more detailed section on [Best Practices for Faster Reviews](#best-practices-for-faster-reviews) at the end of this doc.**
## Run Local Verifications
You can run these local verifications before you submit your PR to predict the
pass or fail of continuous integration.
* Run and pass `make verify` (can take 30-40 minutes)
* Run and pass `make test`
* Run and pass `make test-integration`
## Sign the CLA
You must sign the CLA before your first contribution. [Read more about the CLA.](https://github.com/kubesphere/kubesphere/docs/CLA.md)
If you haven't signed the Contributor License Agreement (CLA) before making a PR,
the `@o8x-ci-robot` will leave a comment with instructions on how to sign the CLA.
# The PR Submit Process
Merging a PR requires the following steps to be completed before the PR will be merged automatically. For details about each step, see the [The Testing and Merge Workflow](#the-testing-and-merge-workflow) section below.
- Sign the CLA (prerequisite)
- Make the PR
- Release notes - do one of the following:
- Add notes in the release notes block, or
- Update the release note label
- Pass all tests
- Get a `/lgtm` from a reviewer
- Get approval from an owner
If your PR meets all of the steps above, it will enter the submit queue to be merged. When it is next in line to be merged, the tests will run a second time. If all tests pass, the PR will be merged automatically.
## Write Release Notes if Needed
Release notes are required for any PR with user-visible changes, such as bug-fixes, feature additions, and output format changes.
If you don't add release notes in the PR template, the `do-not-merge/release-note-label-needed` label is added to your PR automatically after you create it. There are a few ways to update it.
To add a release-note section to the PR description:
For PRs with a release note:
```release-note
Your release note here
```
For PRs that require additional action from users switching to the new release, include the string "action required" (case insensitive) in the release note:
```release-note
action required: your release note here
```
For PRs that don't need to be mentioned at release time, just write "NONE" (case insensitive):
```release-note
NONE
```
The `/release-note-none` comment command can still be used as an alternative to writing "NONE" in the release-note block if it is left empty.
To see how to format your release notes, view the [PR template](https://github.com/) for a brief example. PR titles and body comments can be modified at any time prior to the release to make them friendly for release notes.
// PR template TODO
Release notes apply to PRs on the master branch. For cherry-pick PRs, see the [cherry-pick instructions](cherry-picks.md). The only exception to these rules is when a PR is not a cherry-pick and is targeted directly to the non-master branch. In this case, a `release-note-*` label is required for that non-master PR.
// cherry-pick TODO
Now that your release notes are in shape, let's look at how the PR gets tested and merged.
## The Testing and Merge Workflow
The KubeSphere merge workflow uses comments to run tests and labels for merging PRs.
NOTE: For pull requests that are in progress but not ready for review,
prefix the PR title with `WIP` or `[WIP]` and track any remaining TODOs
in a checklist in the pull request description.
Here's the process the PR goes through on its way from submission to merging:
1. Make the pull request
1. `@o8x-merge-robot` assigns reviewers //TODO
If you're **not** a member of the KubeSphere organization:
1. Reviewer/KubeSphere Member checks that the PR is safe to test. If so, they comment `/ok-to-test`
1. Reviewer suggests edits
1. Push edits to your PR branch
1. Repeat the prior two steps as needed
1. (Optional) Some reviewers prefer that you squash commits at this step
1. Owner is assigned and will add the `/approve` label to the PR
If you are a member, or a member comments `/ok-to-test`, the PR will be considered to be trusted. Then the pre-submit tests will run:
1. Automatic tests run. See the current list of tests on the
1. If tests fail, resolve issues by pushing edits to your PR branch
1. If the failure is a flake, anyone on trusted PRs can comment `/retest` to rerun failed tests
Once the tests pass, all failures are commented as flakes, or the reviewer adds the labels `lgtm` and `approved`, the PR enters the final merge queue. The merge queue is needed to make sure no incompatible changes have been introduced by other PRs since the tests were last run on your PR.
Either the [on call contributor](on-call-rotations.md) will manage the merge queue manually. //TODO
1. The PR enters the merge queue ([http://submit-queue.KubeSphere.io]())
1. The merge queue triggers a test re-run with the comment `/test all [submit-queue is verifying that this PR is safe to merge]`
1. Author has signed the CLA (`cncf-cla: yes` label added to PR)
1. No changes made since last `lgtm` label applied
1. If tests fail, resolve issues by pushing edits to your PR branch
1. If the failure is a flake, anyone can comment `/retest` if the PR is trusted
1. If tests pass, the merge queue automatically merges the PR
That's the last step. Your PR is now merged.
## Marking Unfinished Pull Requests
If you want to solicit reviews before the implementation of your pull request is complete, you should hold your pull request to ensure that the merge queue does not pick it up and attempt to merge it. There are two methods to achieve this:
1. You may add the `/hold` or `/hold cancel` comment commands
2. You may add or remove a `WIP` or `[WIP]` prefix to your pull request title
The GitHub robots will add and remove the `do-not-merge/hold` label as you use the comment commands and the `do-not-merge/work-in-progress` label as you edit your title. While either label is present, your pull request will not be considered for merging.
## Comment Commands Reference
[The commands doc]() contains a reference for all comment commands. //TODO
## Automation
The KubeSphere developer community uses a variety of automation to manage pull requests. This automation is described in detail [in the automation doc](automation.md). //TODO
## How the Tests Work
The tests will post the status results to the PR. If an e2e test fails,
`@o8x-ci-robot` will comment on the PR with the test history and the
comment-command to re-run that test. e.g.
> The following tests failed, say /retest to rerun them all.
# Why was my PR closed?
Pull requests older than 90 days will be closed. Exceptions can be made for PRs that have active review comments, or that are awaiting other dependent PRs. Closed pull requests are easy to recreate, and little work is lost by closing a pull request that subsequently needs to be reopened. We want to limit the total number of PRs in flight to:
* Maintain a clean project
* Remove old PRs that would be difficult to rebase as the underlying code has changed over time
* Encourage code velocity
# Why is my PR not getting reviewed?
A few factors affect how long your PR might wait for review.
If it's the last few weeks of a milestone, we need to reduce churn and stabilize.
Or, it could be related to best practices. One common issue is that the PR is too big to review. Let's say you've touched 39 files and have 8657 insertions. When your would-be reviewers pull up the diffs, they run away - this PR is going to take 4 hours to review and they don't have 4 hours right now. They'll get to it later, just as soon as they have more free time (ha!).
There is a detailed rundown of best practices, including how to avoid too-lengthy PRs, in the next section.
But, if you've already followed the best practices and you still aren't getting any PR love, here are some
things you can do to move the process along:
* Make sure that your PR has an assigned reviewer (assignee in GitHub). If not, reply to the PR comment stream asking for a reviewer to be assigned.
* Ping the assignee (@username) on the PR comment stream, and ask for an estimate of when they can get to the review.
* Ping the assignee on [Slack](http://KubeSphere.slack.com). Remember that a person's GitHub username might not be the same as their Slack username.
* Ping the assignee by email (many of us have publicly available email addresses).
* If you're a member of the organization ping the [team](https://github.com/orgs/KubeSphere/teams) (via @team-name) that works in the area you're submitting code.
* If you have fixed all the issues from a review, and you haven't heard back, you should ping the assignee on the comment stream with a "please take another look" (`PTAL`) or similar comment indicating that you are ready for another review.
Read on to learn more about how to get faster reviews by following best practices.
# Best Practices for Faster Reviews
Most of this section is not specific to KubeSphere, but it's good to keep these best practices in mind when you're making a PR.
You've just had a brilliant idea on how to make KubeSphere better. Let's call that idea Feature-X. Feature-X is not even that complicated. You have a pretty good idea of how to implement it. You jump in and implement it, fixing a bunch of stuff along the way. You send your PR - this is awesome! And it sits. And sits. A week goes by and nobody reviews it. Finally, someone offers a few comments, which you fix up and wait for more review. And you wait. Another week or two go by. This is horrible.
Let's talk about best practices so your PR gets reviewed quickly.
## 0. Familiarize yourself with project conventions
* [Development guide](development.md)
## 1. Is the feature wanted? Make a Design Doc or Sketch PR
Are you sure Feature-X is something the KubeSphere team wants or will accept? Is it implemented to fit with other changes in flight? Are you willing to bet a few days or weeks of work on it?
It's better to get confirmation beforehand. There are two ways to do this:
- Make a proposal doc (in docs/proposals; for example [the QoS proposal](), or reach out to the affected special interest group (SIG). Here's a [list of SIGs](https://github.com/KubeSphere/KubeSphere/docs/sig-list.md)
- Coordinate your effort with [SIG Docs]() ahead of time. //TODO
- Make a sketch PR (e.g., just the API or Go interface). Write or code up just enough to express the idea and the design and why you made those choices
Or, do all of the above.
Be clear about what type of feedback you are asking for when you submit a proposal doc or sketch PR.
Now, if we ask you to change the design, you won't have to re-write it all.
## 2. Smaller Is Better: Small Commits, Small PRs
Small commits and small PRs get reviewed faster and are more likely to be correct than big ones.
Attention is a scarce resource. If your PR takes 60 minutes to review, the reviewer's eye for detail is not as keen in the last 30 minutes as it was in the first. It might not get reviewed at all if it requires a large continuous block of time from the reviewer.
**Breaking up commits**
Break up your PR into multiple commits, at logical break points.
Making a series of discrete commits is a powerful way to express the evolution of an idea or the
different ideas that make up a single feature. Strive to group logically distinct ideas into separate commits.
For example, if you found that Feature-X needed some prefactoring to fit in, make a commit that JUST does that prefactoring. Then make a new commit for Feature-X.
Strike a balance with the number of commits. A PR with 25 commits is still very cumbersome to review, so use
judgment.
**Breaking up PRs**
Or, going back to our prefactoring example, you could also fork a new branch, do the prefactoring there and send a PR for that. If you can extract whole ideas from your PR and send those as PRs of their own, you can avoid the painful problem of continually rebasing.
KubeSphere is a fast-moving codebase - lock in your changes ASAP with your small PR, and make merges be someone else's problem.
Multiple small PRs are often better than multiple commits. Don't worry about flooding us with PRs. We'd rather have 100 small, obvious PRs than 10 unreviewable monoliths.
We want every PR to be useful on its own, so use your best judgment on what should be a PR vs. a commit.
As a rule of thumb, if your PR is directly related to Feature-X and nothing else, it should probably be part of the Feature-X PR. If you can explain why you are doing seemingly no-op work ("it makes the Feature-X change easier, I promise") we'll probably be OK with it. If you can imagine someone finding value independently of Feature-X, try it as a PR. (Do not link pull requests by `#` in a commit description, because GitHub creates lots of spam. Instead, reference other PRs via the PR your commit is in.)
## 3. Open a Different PR for Fixes and Generic Features
**Put changes that are unrelated to your feature into a different PR.**
Often, as you are implementing Feature-X, you will find bad comments, poorly named functions, bad structure, weak type-safety, etc.
You absolutely should fix those things (or at least file issues, please) - but not in the same PR as your feature. Otherwise, your diff will have way too many changes, and your reviewer won't see the forest for the trees.
**Look for opportunities to pull out generic features.**
For example, if you find yourself touching a lot of modules, think about the dependencies you are introducing between packages. Can some of what you're doing be made more generic and moved up and out of the Feature-X package? Do you need to use a function or type from an otherwise unrelated package? If so, promote! We have places for hosting more generic code.
Likewise, if Feature-X is similar in form to Feature-W which was checked in last month, and you're duplicating some tricky stuff from Feature-W, consider prefactoring the core logic out and using it in both Feature-W and
Feature-X. (Do that in its own commit or PR, please.)
## 4. Comments Matter
In your code, if someone might not understand why you did something (or you won't remember why later), comment it. Many code-review comments are about this exact issue.
If you think there's something pretty obvious that we could follow up on, add a TODO.
Read up on [GoDoc](https://blog.golang.org/godoc-documenting-go-code) - follow those general rules for comments.
## 5. Test
Nothing is more frustrating than starting a review, only to find that the tests are inadequate or absent. Very few PRs can touch code and NOT touch tests.
If you don't know how to test Feature-X, please ask! We'll be happy to help you design things for easy testing or to suggest appropriate test cases.
## 6. Squashing and Commit Titles
Your reviewer has finally sent you feedback on Feature-X.
Make the fixups, and don't squash yet. Put them in a new commit, and re-push. That way your reviewer can look at the new commit on its own, which is much faster than starting over.
We might still ask you to clean up your commits at the very end for the sake of a more readable history, but don't do this until asked: typically at the point where the PR would otherwise be tagged `LGTM`.
Each commit should have a good title line (<70 characters) and include an additional description paragraph describing in more detail the change intended.
**General squashing guidelines:**
* Sausage => squash
Do squash when there are several commits to fix bugs in the original commit(s), address reviewer feedback, etc. Really we only want to see the end state and commit message for the whole PR.
* Layers => don't squash
Don't squash when there are independent changes layered to achieve a single goal. For instance, writing a code munger could be one commit, applying it could be another, and adding a precommit check could be a third. One could argue they should be separate PRs, but there's really no way to test/review the munger without seeing it applied, and there needs to be a precommit check to ensure the munged output doesn't immediately get out of date.
A commit, as much as possible, should be a single logical change.
## 7. KISS, YAGNI, MVP, etc.
Sometimes we need to remind each other of core tenets of software design - Keep It Simple, You Aren't Gonna Need It, Minimum Viable Product, and so on. Adding a feature "because we might need it later" is antithetical to software that ships. Add the things you need NOW and (ideally) leave room for things you might need later - but don't implement them now.
## 8. It's OK to Push Back
Sometimes reviewers make mistakes. It's OK to push back on changes your reviewer requested. If you have a good reason for doing something a certain way, you are absolutely allowed to debate the merits of a requested change. Both the reviewer and reviewee should strive to discuss these issues in a polite and respectful manner.
You might be overruled, but you might also prevail. We're pretty reasonable people. Mostly.
Another phenomenon of open-source projects (where anyone can comment on any issue) is the dog-pile - your PR gets so many comments from so many people it becomes hard to follow. In this situation, you can ask the primary reviewer (assignee) whether they want you to fork a new PR to clear out all the comments. You don't HAVE to fix every issue raised by every person who feels like commenting, but you should answer reasonable comments with an explanation.
## 9. Common Sense and Courtesy
No document can take the place of common sense and good taste. Use your best judgment, while you put
a bit of thought into how your work can be made easier to review. If you do these things your PRs will get merged with less friction.
Welcome to KubeSphere! (New Developer Guide)
============================================
_This document assumes that you know what KubeSphere does. If you don't,
try the demo at [https://o8x.io/](https://kubesphere.io/)._
Introduction
------------
Have you ever wanted to contribute to the coolest cloud technology? This
document will help you understand the organization of the KubeSphere project and
direct you to the best places to get started. By the end of this doc, you'll be
able to pick up issues, write code to fix them, and get your work reviewed and
merged.
If you have questions about the development process, feel free to jump into our
[Slack workspace](http://KubeSphere.slack.com/) or join our [mailing
list](https://groups.google.com/forum/#!forum/KubeSphere-dev). If you join the
Slack workspace it is recommended to set your Slack display name to your GitHub
account handle.
Special Interest Groups
-----------------------
KubeSphere developers work in teams called Special Interest Groups (SIGs). At
the time of this writing there are [2 SIGs](sig-list.md).
The developers within each SIG have autonomy and ownership over that SIG's part
of KubeSphere. SIGs organize themselves by meeting regularly and submitting
markdown design documents to the
[KubeSphere/community](https://github.com/KubeSphere/community) repository.
Like everything else in KubeSphere, a SIG is an open, community, effort. Anybody
is welcome to jump into a SIG and begin fixing issues, critiquing design
proposals and reviewing code.
Most people who visit the KubeSphere repository for the first time are
bewildered by the thousands of [open
issues](https://github.com/KubeSphere/KubeSphere/issues) in our main repository.
But now that you know about SIGs, it's easy to filter by labels to see what's
going on in a particular SIG. For more information about our issue system, check
out
[issues.md](https://github.com/KubeSphere/community/blob/master/contributors/devel/issues.md).
//TODO
Downloading, Building, and Testing KubeSphere
---------------------------------------------
This guide is non-technical, so it does not cover the technical details of
working KubeSphere. We have plenty of documentation available under
[github.com/KubeSphere/KubeSphere/docs/](https://github.com/KubeSphere/KubeSphere/docs/).
Check out
[development.md](https://github.com/KubeSphere/KubeSphere/docs/development.md)
for more details.
Pull-Request Process
--------------------
The pull-request process is documented in [pull-requests.md](pull-requests.md).
As described in that document, you must sign the CLA before
KubeSphere can accept your contribution.
The Release Process and Code Freeze
-----------------------------------
Every so often @o8x-merge-robot will refuse to merge your PR, saying something
about release milestones. This happens when we are in a code freeze for a
release. In order to ensure KubeSphere is stable, we stop merging everything
that's not a bugfix, then focus on making all the release tests pass. This code
freeze usually lasts two weeks and happens once per quarter.
If you're new to KubeSphere, you won't have to worry about this too much. After
you've contributed for a few months, you will be added as a [community
member](https://github.com/KubeSphere/KubeSphere/docs/membership.md)
and take ownership of some of the tests. At this point, you'll work with members
of your SIG to review PRs coming into your area and track down issues that occur
in tests.
Thanks for reading!
Markdown is supported
0% .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑!
想要评论请 注册