diff --git a/developer-guide/development/how-to-run-kubesphere-core.md b/developer-guide/development/how-to-run-kubesphere-core.md index 076fd958c..e5c5d8dca 100644 --- a/developer-guide/development/how-to-run-kubesphere-core.md +++ b/developer-guide/development/how-to-run-kubesphere-core.md @@ -1,13 +1,10 @@ # How to Run KubeSphere in Local -This document will explain how to run KubeSphere apiserver locally. - -> Modules similar to KubeSphere apiserver are KubeSphere controller-manageer, Kubesphere iam (also known as KubeSphere account), KubeSphere api-gateway. -> If you need to run these modules locally, you can refer to this document for configuration. +This document will explain how to run KubeSphere apiserver locally. Modules similar to KubeSphere apiserver are KubeSphere controller-manageer, KubeSphere IAM (also known as KubeSphere account), KubeSphere api-gateway. If you need to run these modules locally, you can also refer to this document for configuration. ## Prerequisite -The document [How to build KubeSphere](README.md) elaborates on how to build KubeSphere locally. Make sure you could build KubeSphere successfully. +The document [How to build KubeSphere](/developer-guide/development/README.md) elaborates on how to build KubeSphere locally. Make sure you could build KubeSphere successfully. ## 1. Set up a Kubernetes cluster with KubeSphere installed @@ -19,21 +16,23 @@ You can quickly install a KubeSphere cluster by referring to this [documentation You can refer to this [document](https://kubernetes.io/docs/tasks/tools/install-kubectl/) to install and configure kubectl locally. -## 3. Understand KubeSphere Core's configuration +## 3. Understand KubeSphere core's configuration KubeSphere uses [viper](https://github.com/spf13/viper) to manage the configuration. KubeSphere supports setting up using command line arguments and configuration files. -> We recommend that you use a configuration file for configuration during local development. +> We recommend you use a configuration file during local development. -KubeSphere apiserver needs to communicate with many modules. When you run KubeSphere, you can choose to configure the seperate modules only you care about. +KubeSphere apiserver needs to communicate with many modules. When you run KubeSphere, you can choose to configure the modules you care about only. During the development of KubeSphere apiserver, you must configure at least the relevant part of Kubernetes to ensure that KubeSphere apiserver can be started. Below is a sample configuration of KubeSphere apiserver: -> Note: In the default configuration, we use Kubernetes service name to access the service. -> In a remote cluster, you may need to use external network exposure to connect to the cluster's internal services. -> Or you can refer to the [documentation](How-to-connect-remote-service.md) to use `telepresence` to connect to remote services +> Note: +> +> - In the default configuration, we use Kubernetes service name to access the service. +> - In a remote cluster, you may need to use external network exposure to connect to the cluster's internal services. +> - Or you can refer to the [documentation](How-to-connect-remote-service.md) to use `telepresence` to connect to remote services. ```yaml kubernetes: @@ -102,13 +101,12 @@ notification: endpoint: http://notification.kubesphere-alerting-system.svc ``` -## 4. Set Up KubeSphere Core's configuration +## 4. Set up KubeSphere core's configuration -The KubeSphere Core module will read the `kubesphere.yaml` file in the current directory and the `kubesphere.yaml` file in the `/etc/kubesphere` directory, then load the configuration at startup. -You can choose a path to set your configuration locally. +The KubeSphere core module will read the `kubesphere.yaml` file from the current directory, if not found, then search the `/etc/kubesphere` directory for the file, then load the configuration at startup. You can also choose a specific path to set your configuration locally. ## 5. Run KubeSphere apiserver -You can execute `go run cmd/ks-apiserver/apiserver.go` in the `$GOPATH/src/kubesphere.io/kubesphere` directory to start KubeSphere apiserver +Execute `go run cmd/ks-apiserver/apiserver.go` in the `$GOPATH/src/kubesphere.io/kubesphere` directory to start KubeSphere apiserver. -> If you want to understand the specific meaning of each configuration, you can view it by `go run cmd/ks-apiserver/apiserver.go --help` or read the module's design and developer documentation. +If you want to understand the specific meaning of each configuration, you can view it by `go run cmd/ks-apiserver/apiserver.go --help` or read the module's design and development documents. diff --git a/developer-guide/development/kubesphere-code-layout.md b/developer-guide/development/kubesphere-code-layout.md index 46b075d2a..20d6acce0 100644 --- a/developer-guide/development/kubesphere-code-layout.md +++ b/developer-guide/development/kubesphere-code-layout.md @@ -1,53 +1,52 @@ # KubeSphere File Tree -This document describes the directory structure of the KubeSphere repository. +This document describes the directory structure of the KubeSphere backend repository. - -``` -├── api // Automatically generated API documentation +```yaml +├── api // automatically generated API documentation │   ├── api-rules -│   ├── ks-openapi-spec // REST API documentation provided by kubesphere apiserver -│   └── openapi-spec // REST API documentation provided by kubesphere apiserver -├── build // Dockerfile -│   ├── hypersphere +│   ├── ks-openapi-spec // REST API documentation provided by KubeSphere apiserver +│   └── openapi-spec // REST API documentation provided by KubeSphere apiserver +├── build // Dockerfile +│   ├── hypersphere │   ├── ks-apigateway │   ├── ks-apiserver │   ├── ks-controller-manager │   ├── ks-iam │   └── ks-network -├── cmd // Main applications for KubeSphere. -│   ├── controller-manager // Kubesphere Controller Manger, used to reconcile KubeSphere CCRD +├── cmd // main applications for KubeSphere +│   ├── controller-manager // KubeSphere Controller Manger, used to reconcile KubeSphere CRD │   │   └── app -│   ├── hypersphere +│   ├── hypersphere │   ├── ks-apigateway // KubeSphere API gateway │   │   └── app │   ├── ks-apiserver // KubeSphere REST API server │   │   └── app -│   ├── ks-iam // KubeSphere iam service +│   ├── ks-iam // KubeSphere IAM service │   │   └── app │   └── ks-network ├── config // CRD config files │   ├── crds // CRD yaml files │   ├── default // kustomization yaml files │   ├── manager // controller manager yaml files -│   ├── rbac // rbac yaml files +│   ├── rbac // RBAC yaml files │   ├── samples // CRD sample -│   └── webhook // webhppk yaml files -├── docs +│   └── webhook // webhook yaml files +├── docs │   ├── en │   │   ├── concepts-and-designs │   │   └── guides │   └── images -├── hack // Script files to help people develop +├── hack // script files to help people develop │   └── lib -├── pkg // Library code. -│   ├── api // Structure definitions for REST APIs +├── pkg // library code. +│   ├── api // structure definitions for REST APIs │   │   ├── devops │   │   ├── logging │   │   └── monitoring -│   ├── apigateway +│   ├── apigateway │   │   └── caddy-plugin -│   ├── apis // Structure definitions for CRDs +│   ├── apis // structure definitions for CRDs │   │   ├── devops │   │   ├── network │   │   ├── servicemesh @@ -72,12 +71,12 @@ This document describes the directory structure of the KubeSphere repository. │   │   ├── terminal │   │   ├── workloadstatuses │   │   └── workspaces -│   ├── client //Automatically generated CRD client +│   ├── client // automatically generated CRD client │   │   ├── clientset │   │   ├── informers │   │   └── listers │   ├── constants // common constants -│   ├── controller // controller manger's reconciliation logic +│   ├── controller // controller manager reconciliation logic │   │   ├── application │   │   ├── clusterrolebinding │   │   ├── destinationrule @@ -89,11 +88,11 @@ This document describes the directory structure of the KubeSphere repository. │   │   ├── storage │   │   ├── virtualservice │   │   └── workspace -│   ├── db // Database ORM Framework +│   ├── db // database ORM framework │   │   ├── ddl │   │   ├── schema │   │   └── scripts -│   ├── gojenkins // Jenkins Go Client +│   ├── gojenkins // Jenkins Go client │   │   ├── _tests │   │   └── utils │   ├── informers @@ -108,7 +107,7 @@ This document describes the directory structure of the KubeSphere repository. │   │   ├── servicemesh │   │   ├── tenant │   │   └── terminal -│   ├── models // Data processing part of REST API +│   ├── models // data processing part of REST API │   │   ├── components │   │   ├── devops │   │   ├── git @@ -131,7 +130,7 @@ This document describes the directory structure of the KubeSphere repository. │   │   ├── terminal │   │   ├── workloads │   │   └── workspaces -│   ├── server // Data processing part of REST API +│   ├── server // data processing part of REST API │   │   ├── config │   │   ├── errors │   │   ├── filter @@ -157,11 +156,10 @@ This document describes the directory structure of the KubeSphere repository. │   ├── version │   └── webhook ├── test // e2e test code -│   ├── e2e -├── tools // tools to genereate API docs -│   ├── cmd -│   │   ├── crd-doc-gen // gen CRD API docs -│   │   └── doc-gen // gen REST API docs -│   └── lib - +│   └── e2e +└── tools // tools to generate API docs +    ├── cmd +    │   ├── crd-doc-gen // gen CRD API docs +    │   └── doc-gen // gen REST API docs +    └── lib ``` diff --git a/developer-guide/development/pull-requests.md b/developer-guide/development/pull-requests.md index 45dbc6309..e4b54d30d 100644 --- a/developer-guide/development/pull-requests.md +++ b/developer-guide/development/pull-requests.md @@ -1,33 +1,30 @@ # 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. +This document 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) + - [Run Local Verifications](#run-local-verifications) - [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) + - [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) +## 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 writing code to contribute to KubeSphere, see the [development guide](/developer-guide/development/development-workflow.md). -# Before You Submit a PR +**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 document.** -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). +### Run Local Verifications -**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.** +You can run these local verifications before you submit your PR to predict the pass or fail of continuous integration. -## Run Local Verifications +## The PR Submit Process -You can run these local verifications before you submit your PR to predict the -pass or fail of continuous integration. - -# 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. +Merging a PR requires the following steps to be completed before the PR is merged automatically. For details about each step, see the [The Testing and Merge Workflow](#the-testing-and-merge-workflow) section below. - Make the PR - Release notes - do one of the following: @@ -39,7 +36,7 @@ Merging a PR requires the following steps to be completed before the PR will be 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 +### 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. @@ -76,48 +73,47 @@ Release notes apply to PRs on the master branch. For cherry-pick PRs, see the [c 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 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. + +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 +2. `@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 +1. Reviewer/KubeSphere member checks that the PR is safe to test. If so, they comment `/ok-to-test` +2. Reviewer suggests edits +3. Push edits to your PR branch +4. Repeat the prior two steps as needed +5. (Optional) Some reviewers prefer that you squash commits at this step +6. 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 +1. Automatic tests run. See the current list of tests on the PR +2. If tests fail, resolve issues by pushing edits to your PR branch +3. 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 +2. The merge queue triggers a test re-run with the comment `/test all [submit-queue is verifying that this PR is safe to merge]` + 2.1. Author has signed the CLA (`cncf-cla: yes` label added to PR) + 2.2. No changes made since last `lgtm` label applied +3. If tests fail, resolve issues by pushing edits to your PR branch +4. If the failure is a flake, anyone can comment `/retest` if the PR is trusted +5. If tests pass, the merge queue automatically merges the PR That's the last step. Your PR is now merged. -## Marking Unfinished Pull Requests +### 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: @@ -126,16 +122,15 @@ If you want to solicit reviews before the implementation of your pull request is 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//TODO +### Comment Commands Reference//TODO [The commands doc]() contains a reference for all comment commands. //TODO -## Automation//TODO +### Automation//TODO 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 e2e Tests Work//TODO +### How the e2e Tests Work//TODO 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