diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 00000000..84a3f18a --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,5 @@ +# KubeEdge Community Code of Conduct + +KubeEdge follows the [CNCF Code of Conduct](https://github.com/cncf/foundation/blob/master/code-of-conduct.md). + +Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at kubeedge@gmail.com. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..300ec9c0 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,7 @@ +# Contributing Guidelines + +Welcome to Sedna. We are excited about the prospect of you joining our [community](https://github.com/kubeedge/community)! The KubeEdge community abides by the CNCF [code of conduct](CODE-OF-CONDUCT.md). Here is an excerpt: + +_As contributors and maintainers of this project, and in the interest of fostering an open and welcoming community, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities._ + +To learn more about contributing to the [Sedna code repo](README.md), check out the [contributing guide](docs/contributing/getting-started.md). diff --git a/README.md b/README.md index 987f6020..2acb5b64 100644 --- a/README.md +++ b/README.md @@ -105,11 +105,9 @@ If you need support, start with the [troubleshooting guide](./docs/troubleshooti If you have questions, feel free to reach out to us in the following ways: - [slack channel](https://app.slack.com/client/TDZ5TGXQW/C01EG84REVB/details) - ## License diff --git a/README_zh.md b/README_zh.md index 9dc67c8c..0072709c 100644 --- a/README_zh.md +++ b/README_zh.md @@ -91,12 +91,12 @@ Sedna的安装文档请参考[这里](/docs/setup/install.md)。 如果您有任何疑问，请以下方式与我们联系： - [slack channel](https://app.slack.com/client/TDZ5TGXQW/C01EG84REVB/details) - + ## 许可证 diff --git a/docs/contributing/control-plane/add-a-new-synergy-feature.md b/docs/contributing/control-plane/add-a-new-synergy-feature.md new file mode 100644 index 00000000..44a6d676 --- /dev/null +++ b/docs/contributing/control-plane/add-a-new-synergy-feature.md @@ -0,0 +1,71 @@ +### Discussion About New Feature +Discuss the new feature that you want to add with us on [our meeting](/README.md#meeting) in the following dimensions: +1. User Cases, Values +1. API +1. Architecture, A Main Process + +#### Submitting Your Proposal +you can refer to [existing proposals] for proposal template. + +### Developing + +#### Developing on control plane +- [The development guide of control plane](./development.md) + +Suppose you are going to add a synergy feature named `foobar` with versioned `v1alpha1`. +1. Add `foobar` APIs + ```shell + cd pkg/apis/sedna/v1alpha1/ + # code the api + touch foobar.go + ``` + +1. Code controller logic based on the [k8s operator pattern] + + ```shell + mkdir -p pkg/globalmanager/controllers/foobar/ + cd pkg/globalmanager/controllers/foobar/ + touch foobar.go + ``` + +1. Code upstream logic if any + ```shell + # GM part + cd pkg/globalmanager/controllers/foobar/ + touch upstream.go + + # LC part + mkdir pkg/localcontroller/managers/foobar/ + cd pkg/localcontroller/managers/foobar/ + touch foobar.go + ``` + +1. Code downstream logic if any + ```shell + # GM part + cd pkg/globalmanager/controllers/foobar/ + touch downstream.go + + # LC part + cd pkg/localcontroller/managers/foobar/ + touch foobar.go + ``` + +About debugging GM/LC: + - [debug GM](debug-gm.md) + - [debug LC](debug-lc.md) + +Also see [coding conventions][k8s coding convention] for clean code. + +#### Developing Workers TBD + + +#### Submitting Your Code + +When development has been done and ready to submit your work, see [pull request guide][kubernetes pull request guide] for more details if you don't know. + +[existing proposals]: /docs/proposals + +[k8s coding convention]: https://github.com/kubernetes/community/blob/master/contributors/guide/coding-conventions.md +[kubernetes pull request guide]: https://github.com/kubernetes/community/blob/master/contributors/guide/style-guide.md +[k8s operator pattern]: https://kubernetes.io/docs/concepts/extend-kubernetes/operator/ diff --git a/docs/contributing/control-plane/debug-gm.md b/docs/contributing/control-plane/debug-gm.md new file mode 100644 index 00000000..7f368a92 --- /dev/null +++ b/docs/contributing/control-plane/debug-gm.md @@ -0,0 +1,57 @@ +This document is intended to provide contributors with an introduction to develop [GM(GlobalManager)][framework] of the Sedna project. + +### Debug GM +1\. config GM: + +The config file is the yaml format: + +```yaml +kubeConfig: "" +namespace: "" +websocket: + port: 9000 +localController: + server: http://localhost:9100 +``` + +1. `kubeConfig`: kubernetes config file, default `""` +1. `namespace`: the namespace GM watches, `""` means that gm watches all namespaces, default `""`. +1. `websocket`: since the current limit of kubeedge(1.5), GM needs to build the websocket channel for communicating between GM and LCs. +1. `localController`: + - `server`: to be injected into the worker to connect LC. + +Generate a config yaml: + +```shell +cat > gm.yaml < **Note**: If you have already run Sedna by following the [install doc], and decide to run LC in-place, you don't need to setup these environments, run `make lcimage` and `kubectl -n sedna delete pod lc-`. + +2\. compile and run LC directly: + +```shell +make WHAT=lc +_output/bin/sedna-lc -v4 +``` + +Alternatively you can debug LC with [golang delve]: + +```shell +dlv debug cmd/sedna-lc/sedna-lc.go -- -v4 +``` + +[install doc]: /docs/setup/install.md +[golang delve]: https://github.com/go-delve/delve +[framework]: /docs/proposals/architecture.md#architecture diff --git a/docs/contributing/control-plane/development.md b/docs/contributing/control-plane/development.md new file mode 100644 index 00000000..860cd8de --- /dev/null +++ b/docs/contributing/control-plane/development.md @@ -0,0 +1,109 @@ +# Development Guide +This document is intended to provide contributors with an introduction to developing the control plane of the Sedna project. +There are two components in our control plane: [GM(Global Manager) and LC(Local Controller)][framework]. + +## Overview + +Sedna provides various utilities for development wrapped in `make`. + +Most scripts require more or less only `make` + `bash` on the host, and generally +stick to POSIX utilities. Some scripts use `docker` e.g. for image building or +to use docker images containing special tools. + +## Read Conventions Before Coding +- [k8s coding convention] +- [k8s api convention] if you want to add or update api. + +## Building +Before continuing, you need to follow the [prerequisites installation guide] if you haven't done it yet. + +### Building Code + +```shell +# build GM +make WHAT=gm + +# build LC +make WHAT=lc + +# build GM/LC both +make +``` + +`_output/bin` will contain the freshly built binaries `sedna-gm` and `sedna-lc` upon a successful build. + +### Add or Update API +If you add or update APIs in `pkg/apis/`, you need to run: +1. run `bash hack/update-codegen.sh` to update client-go code in `pkg/client`. + > **Note**: you need to checkout the code to `$GOPATH/src/github.com/kubeedge/sedna`. +1. run `make crds` to update the api definition. +1. run `kubectl replace -f build/crds/` to update your kubernetes environment. + + +### Add or Update Dependencies + +Run the following commands to update [Go Modules]: + +``` +go mod tidy +go mod vendor + +# Or: hack/update-vendor.sh +``` + +Run `hack/update-vendor-licenses.sh` to update [vendor licenses](/LICENSES). + +### Running Sedna + +- [See here to run GM](debug-gm.md) +- [See here to run LC](debug-lc.md) + + +### Building Images + +To build the GM/LC base images: + +```shell +# build GM +make gmimage + +# build LC +make lcimage +``` + +## Run verification +You need to run the verification tests locally to give your pull request the best chance of being accepted. + +To run all verification tests, use this command: + +```shell +make verify +``` + +## Debugging +TBD + + +## Testing +TBD + +### E2E Testing +TBD + +## Linting +You can run all of our lints at once with `make lint`. + +Lints include: +- [golangci-lint] with [a custom config](/.golangci.yml) to lint Go sources. + + +## CI +We use [GitHub Actions] which are configured in [.github/workflows](/.github/workflows) in the Sedna repo. + +[golangci-lint]: https://github.com/golangci/golangci-lint +[GitHub Actions]: https://github.com/features/actions +[go modules]: https://github.com/golang/go/wiki/Modules +[k8s coding convention]: https://github.com/kubernetes/community/blob/master/contributors/guide/coding-conventions.md +[k8s api convention]: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md +[prerequisites installation guide]: /docs/contributing/prepare-environment.md +[framework]: /docs/proposals/architecture.md#architecture diff --git a/docs/contributing/getting-started.md b/docs/contributing/getting-started.md new file mode 100644 index 00000000..464d7d73 --- /dev/null +++ b/docs/contributing/getting-started.md @@ -0,0 +1,69 @@ +This guide covers how to start contributing to Sedna 😄 + +## 1. Familiarize Yourself With Contributing to Sedna + +### Setup GitHub Account + +Sedna is developed on [GitHub][github] and will require +an account for contribution. + +### Check The Kubernetes Contributor Guides + +You may come back to this later, but we highly recommend reading these: + +- [Kubernetes Contributor Guide](https://git.k8s.io/community/contributors/guide) + - Main contributor documentation, or you can just jump directly to the [contributing section](https://git.k8s.io/community/contributors/guide#contributing) +- [Contributor Cheat Sheet](https://git.k8s.io/community/contributors/guide/contributor-cheatsheet) + - Common resources for existing developers + + +### Read The Sedna Docs + +These [proposals] cover framework and multi edge-cloud synergy capabilities of the project, which may be helpful to review before contributing. + +### Reaching Out + +Issues are tracked on GitHub. Please check [the issue tracker][issues] to see +if there is any existing discussion or work related to your interests. + +In particular, if you're just getting started, you may want to look for issues +labeled good first issue or help wanted which are standard labels in the Kubernetes project. +The help wanted label marks issues we're actively seeking help with while good first issue is additionally applied to a subset of issues we think will be particularly good for newcomers. + +See [Kubernetes help wanted] for best practices. + +If you're interested in working on any of these, leave a comment to let us know! + +And please reach out in general for bugs, feature requests, and other issues! +If you do not see anything, please [file a new issue][file-an-issue]. + +> **NOTE**: _Please_ file an enhancement / [feature request issue][file-a-fr] to discuss features before filing a PR (ideally even before writing any code), we have a lot to consider with respect to our +> existing users and future support when accepting any new feature. +> +> To streamline the process, please reach out and discuss the concept and design +> / approach ASAP so the maintainers and community can get involved early. + + +## 2. What's Next? + +- If you're looking to contribute documentation improvements, you'll specifically want to see the [kubernetes documentation style guide] before [filing an issue][file-an-issue]. + +- If you're planning to contribute code changes, you'll want to read the [development preparation guide] next. + +- If you're planning to add a new synergy feature directly, you'll want to read the [guide][add-feature-guide] next. + +When done, you can also refer our [recommended Git workflow] and [pull request best practices] before submitting a pull request. + +[proposals]: /docs/proposals +[development preparation guide]: ./prepare-environment.md +[add-feature-guide]: control-plane/add-a-new-synergy-feature.md + +[issues]: https://github.com/kubeedge/sedna/issues +[file-an-issue]: https://github.com/kubeedge/sedna/issues/new/choose +[file-a-fr]: https://github.com/kubeedge/sedna/issues/new?labels=kind%2Ffeature&template=enhancement.md + +[github]: https://github.com/ +[kubernetes documentation style guide]: https://github.com/kubernetes/community/blob/master/contributors/guide/style-guide.md +[recommended Git workflow]: https://github.com/kubernetes/community/blob/master/contributors/guide/github-workflow.md#workflow +[pull request best practices]: https://github.com/kubernetes/community/blob/master/contributors/guide/pull-requests.md#best-practices-for-faster-reviews +[Kubernetes help wanted]: https://www.kubernetes.dev/docs/guide/help-wanted/ diff --git a/docs/contributing/prepare-environment.md b/docs/contributing/prepare-environment.md new file mode 100644 index 00000000..3505ff9a --- /dev/null +++ b/docs/contributing/prepare-environment.md @@ -0,0 +1,80 @@ +This document helps you prepare environment for developing code for Sedna. +If you follow this guide and find some problem, please fill an issue to update this file. + +## 1. Install Tools +### Install Git + +Sedna is managed with [git], and to develop locally you +will need to install `git`. + +You can check if `git` is already on your system and properly installed with +the following command: + +``` +git --version +``` + +### Install Go(optional) + +All Sedna's control components(i.e. [GM/LC][framework]) are written in the [Go][golang]. +If you are planning to change them, you need to set up Go. + +Sedna currently builds with Go 1.16, install or upgrade [Go using the instructions for your operating system][golang]. + +You can check if Go is in your system with the following command: + +``` +go version +``` + +## 2. Clone the code + +Clone the `Sedna` repo: + +```shell +git clone http://github.com/kubeedge/sedna.git +``` + +**Note**: If you want to add or change API in [pkg/apis](/pkg/apis), you need to checkout the code to `$GOPATH/src/github.com/kubeedge/sedna`. + +## 3. Set up Kubernetes/KubeEdge(optional) +If you are planning to run or debug Sedna, you need to set up Kubernetes and KubeEdge. + +Sedna requires Kubernetes version 1.16 or higher with CRD support. + +Sedna requires KubeEdge version 1.5 or higher with edge support. + +> **Note**: You need to check [the Kubernetes compatibility of KubeEdge][kubeedge-k8s-compatibility]. + +### Install Kubernetes + +Follow [Kubernetes setup guides][k8s-setup] to set up and run Kubernetes, like: +> If you're learning Kubernetes, use the [tools][k8s-tools] to set up a Kubernetes cluster on a local machine, e.g.: +> * [Installing Kubernetes with Kind][kind] +> * [Installing Kubernetes with Minikube][minikube] + + +### Install KubeEdge + +Please follow [the kubeedge instructions][kubeedge] to install KubeEdge. + + +## 4. What's Next? + +Once you've set up the prerequisites, continue with: +- See [control plane development guide] +for more details about how to build & test Sedna. +- See [lib development guide TBD] for more details about how to develop AI algorithms and worker images based on [sedna lib code](/lib). + +[git]: https://git-scm.com/ +[framework]: /docs/proposals/architecture.md#architecture +[github]: https://github.com/ +[golang]: https://golang.org/doc/install +[k8s-setup]: https://kubernetes.io/docs/setup/ +[k8s-tools]: https://kubernetes.io/docs/tasks/tools +[minikube]: https://minikube.sigs.k8s.io/docs/start/ +[kind]: https://kind.sigs.k8s.io +[kubeedge]: https://kubeedge.io/en/docs/ +[kubeedge-k8s-compatibility]: https://github.com/kubeedge/kubeedge#kubernetes-compatibility + +[control plane development guide]: ./control-plane/development.md