diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..02a23b5 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,133 @@ +# Contributing to Openkruise + +Welcome to Openkruise! Openkruise consists several repositories under the organization. +We encourage you to help out by reporting issues, improving documentation, fixing bugs, or adding new features. +Please also take a look at our code of conduct, which details how contributors are expected to conduct themselves as part of the Openkruise community. + +## Reporting issues + +To be honest, we regard every user of Openkruise as a very kind contributor. +After experiencing Openkruise, you may have some feedback for the project. +Then feel free to open an issue. + +There are lot of cases when you could open an issue: + +- bug report +- feature request +- performance issues +- feature proposal +- feature design +- help wanted +- doc incomplete +- test improvement +- any questions on project +- and so on + +Also we must remind that when filing a new issue, please remember to remove the sensitive data from your post. +Sensitive data could be password, secret key, network locations, private business data and so on. + +## Code and doc contribution + +Every action to make Openkruise better is encouraged. +On GitHub, every improvement for Openkruise could be via a PR (short for pull request). + +- If you find a typo, try to fix it! +- If you find a bug, try to fix it! +- If you find some redundant codes, try to remove them! +- If you find some test cases missing, try to add them! +- If you could enhance a feature, please DO NOT hesitate! +- If you find code implicit, try to add comments to make it clear! +- If you find code ugly, try to refactor that! +- If you can help to improve documents, it could not be better! +- If you find document incorrect, just do it and fix that! +- ... + +### Workspace Preparation + +To put forward a PR, we assume you have registered a GitHub ID. +Then you could finish the preparation in the following steps: + +1. **Fork** Fork the repository you wish to work on. You just need to click the button Fork in right-left of project repository main page. Then you will end up with your repository in your GitHub username. +2. **Clone** your own repository to develop locally. Use `git clone https://github.com//.git` to clone repository to your local machine. Then you can create new branches to finish the change you wish to make. +3. **Set remote** upstream to be `https://github.com/openkruise/.git` using the following two commands: + +```bash +git remote add upstream https://github.com/openkruise/.git +git remote set-url --push upstream no-pushing +``` + +Note: `` above is `rollouts` if you want to contribute codes to Kruise Rollout. + +Adding this, we can easily synchronize local branches with upstream branches. + +4. **Create a branch** to add a new feature or fix issues + +Update local working directory: + +```bash +cd +git fetch upstream +git checkout master +git rebase upstream/master +``` + +Create a new branch: + +```bash +git checkout -b +``` + +Make any change on the new-branch then build and test your codes. + +### PR Description + +PR is the only way to make change to project files. +To help reviewers better get your purpose, PR description could not be too detailed. +We encourage contributors to follow the [PR template](./.github/PULL_REQUEST_TEMPLATE.md) to finish the pull request. + +### Developing Environment + +As a contributor, if you want to make any contribution to Kruise project, we should reach an agreement on the version of tools used in the development environment. +Here are some dependents with specific version: + +- Golang : v1.18+ +- Kubernetes: v1.19+ + +### Developing guide + +There's a `Makefile` in the root folder which describes the options to build and install. Here are some common ones: + +```bash +# Generate code and manifests e.g. CRD, RBAC YAML files etc, and build the controller manager binary +make build + +# Run the unit tests +make test +``` + +**There are some guide documents for contributors in [./docs/contributing/](./docs/contributing), such as debug guide to help you test your own branch in a Kubernetes cluster.** + +### Proposals + +If you are going to contribute a feature with new API or needs significant effort, please submit a proposal in [./docs/proposals/](./docs/proposals) first. + +## Engage to help anything + +We choose GitHub as the primary place for Openkruise to collaborate. +So the latest updates of Openkruise are always here. +Although contributions via PR is an explicit way to help, we still call for any other ways. + +- reply to other's issues if you could; +- help solve other user's problems; +- help review other's PR design; +- help review other's codes in PR; +- discuss about Openkruise to make things clearer; +- advocate Openkruise technology beyond GitHub; +- write blogs on Openkruise and so on. + +In a word, **ANY HELP IS CONTRIBUTION**. + +## Join Openkruise as a member + +It is also welcomed to join Openkruise team if you are willing to participate in Openkruise community continuously and keep active. +Please read and follow the [Community Membership](https://github.com/openkruise/community/blob/master/community-membership.md). diff --git a/README.md b/README.md index d3496e7..5adf453 100644 --- a/README.md +++ b/README.md @@ -22,6 +22,9 @@ Kruise Rollouts is a **Bypass** component that offers **Advanced Progressive Del ## Quick Start - See [Getting Started](https://openkruise.io/rollouts/introduction/) documents in OpenKruise official website. +## Contributing +You are warmly welcome to hack on Kruise Rollout. We have prepared a detailed guide [CONTRIBUTING.md](CONTRIBUTING.md). + ## Community Active communication channels: diff --git a/docs/contributing/debug.md b/docs/contributing/debug.md new file mode 100644 index 0000000..fc89d5d --- /dev/null +++ b/docs/contributing/debug.md @@ -0,0 +1,92 @@ +# How to Debug Your Kruise Rollout + +## Way 1: Debug your kruise Rollout with Pod (Recommended) +### First Step: Start your kubernetes cluster +#### Requirements: +- Linux system, MacOS, or Windows Subsystem for Linux 2.0 (WSL 2) +- Docker installed (follow the [official docker installation guide](https://docs.docker.com/get-docker/) to install if need be) +- Kubernetes cluster >= v1.19.0 +- Kubectl installed and configured + +Kruise Rollout relies on Kubernetes as control plane. The control plane could be any managed Kubernetes offering or your own cluster. + +For local deployment and test, you could use [kind](https://kind.sigs.k8s.io/) or [minikube](https://minikube.sigs.k8s.io/docs/start/). For production usage, you could use Kubernetes services provided by cloud providers. +#### Option 1: Start your kubernetes cluster with kind (Recommended) +Follow [this guide](https://kind.sigs.k8s.io/docs/user/quick-start/#installation) to install kind. + +Then spins up a kind cluster: +```shell +cat <` to specify the target image name. e.g., `export IMG=$DOCKERID/kruise-rollout:test`; +- step 2: `make docker-build` to build the image locally and `make docker-push` to push the image to registry; +- step 3: `export KUBECONFIG=` to specify the k8s cluster config. e.g., `export KUBECONFIG=$~/.kube/config`; +- step 4: + - 4.1: `make deploy` to deploy Rollout to the k8s cluster with the `IMG` you have packaged, if the cluster has not installed Rollout or has installed via `make deploy`; + - 4.2: if the cluster has installed Rollout via helm chart, we suggest you just update your `IMG` into it with `kubectl set image -n kruise-rollout deployment kruise-rollout-controller-manager manager=${IMG}`; + +Tips: +- You have to run `./scripts/uninstall.sh` to uninstall Rollout if you installed it using `make deploy`. + +#### 3.View logs of your Rollout +You can perform manual tests and use `kubectl logs -n kruise-rollout ` to check controller logs for debugging, and you can see your `` by applying `kubectl get pod -n kruise-rollout`. + +## Way 2: Debug your Rollout locally (NOT Recommended) +Kubebuilder default `make run` does not work for webhooks since its scaffolding code starts webhook server +using kubernetes service and the service usually does not work in local dev environment. + +We workarounds this problem by allowing to start webbook server in local host directly. +With this fix, one can start/debug Rollout process locally +which connects to a local or remote Kubernetes cluster. Several extra steps are needed to make it work: + +**Setup host and run your Rollout** + +First, make sure your kubernetes cluster is running. + +Second, **make sure `kube-apiserver` could connect to your local machine.** + +Then, run rollout locally with `WEBHOOK_HOST` env: + +```bash +export KUBECONFIG=${PATH_TO_CONFIG} +export WEBHOOK_HOST=${YOUR_LOCAL_IP} + +make install +make run +```