Enrich contributor guidance and remove redun… (#548)

docsite/docs/developer/contributor-guidance.md

@@ -20,7 +20,7 @@ To get started with developing for our project, please refer to our [Development
 
 ## Deploying Changes
 
-If you are working on changes that require deployment, look at our [Deployment Guide](develop-locally.md) for detailed instructions on how to deploy and test your changes in a production-like environment. This ensures that all changes are vetted for stability and compatibility before being integrated.
+If you are working on changes that require deployment, look at our [Deployment Guide](deploy-locally.md) for detailed instructions on how to deploy and test your changes in a production-like environment. This ensures that all changes are vetted for stability and compatibility before being integrated.
 
 ## How to Contribute
 

docsite/docs/developer/develop-locally.md

@@ -1,16 +1,76 @@
 # Develop ob-operator locally
 
-Tips: In this tutorial, we'll disable webhook validation and run manager controller on our laptop. The controller manager will communicate with kubernetes cluster by local .kube/config configuration file.
-
-## Background
+## Introduction
 
 ob-operator depends on [kubebuilder](https://kubebuilder.io/introduction), an operator framework maintained by kubernetes SIGS. It offers convenient utilities to bootstrap an operator and manage API types in it. Like other operator frameworks, kubebuilder depends on kubernetes [controller runtime](https://github.com/kubernetes-sigs/controller-runtime) either, which is an excellent reference to know how kubernetes dispatch events and reconcile resources.
 
-## Disable Webhook and CertManager
+## Requirements
+
+- Go 1.22 or above is required to build ob-operator, you can refer to the [official website](https://go.dev/) to setup go environment.
+- [make](https://www.gnu.org/software/make/) is used for a variety of build and test actions.
+- kubebuilder is used as k8s operator framework. it's highly recommended to read [kubebuilder books](https://book.kubebuilder.io/). 
+- Access to a kubernetes cluster is required to develop and test the operator. You can use [minikube](https://minikube.sigs.k8s.io/docs/), [kind](https://kind.sigs.k8s.io/docs/user/quick-start/) or [k3s](https://k3s.io/) to create a local kubernetes cluster.
+
+## Modify and Apply CRDs
+
+### Modify definition of CRDs
+
+`ob-operator` uses kubebuilder as operator framework, which generates CRDs in YAML format from Go code lies in `api/v1alpha1` directory. If you have modified the Go code, for example adding a new field to `OBClusterSpec` in `api/v1alpha1/obcluster_types.go`, you need to regenerate the CRDs by running `make generate manifests fmt`. Then you will see changes in `config/crd/bases/oceanbase.oceanbase.com_xxx.yaml` files.
+
+### Apply the Changes
+
+You can apply the changes of CRDs to kubernetes cluster by running `make install`. This command will apply the CRDs to the kubernetes cluster.
+
+You will see output like the following after executing `kubectl get crds` command if the CRDs are successfully applied:
+
+```shell
+$ kubectl get crds | grep oceanbase.oceanbase.com
+obclusters.oceanbase.oceanbase.com               2024-01-01T00:00:00Z
+obparameters.oceanbase.oceanbase.com             2024-01-01T00:00:00Z
+obresourcerescues.oceanbase.oceanbase.com        2024-01-01T00:00:00Z
+observers.oceanbase.oceanbase.com                2024-01-01T00:00:00Z
+obtenantbackuppolicies.oceanbase.oceanbase.com   2024-01-01T00:00:00Z
+obtenantbackups.oceanbase.oceanbase.com          2024-01-01T00:00:00Z
+obtenantoperations.oceanbase.oceanbase.com       2024-01-01T00:00:00Z
+obclusteroperations.oceanbase.oceanbase.com      2024-01-01T00:00:00Z
+obtenantrestores.oceanbase.oceanbase.com         2024-01-01T00:00:00Z
+obtenants.oceanbase.oceanbase.com                2024-01-01T00:00:00Z
+obzones.oceanbase.oceanbase.com                  2024-01-01T00:00:00Z
+```
+
+## Modify and Run ob-operator
+
+ob-operator acts as a controller manager, which watches the resources in kubernetes cluster and reconciles them. The controller manager is generated by kubebuilder, and the main logic lies in `internal/{controller,resource}` and `pkg/coordinator` directories.
+
+### Build and Deploy
+
+After modifying the code, you can build the docker image by running `make docker-build docker-push IMG=<your-image-name>`. Then you can deploy the controller manager to the kubernetes cluster by running `make deploy IMG=<your-image-name>`.
+
+If the docker need root permission to build, you can run building command with `sudo`, like
+
+```bash
+sudo make docker-build IMG=<your-image-name>
+make docker-push IMG=<your-image-name> # If you need to push the image to a registry
+make deploy IMG=<your-image-name>
+```
+
+:::tip
+If the developing machine and the deploying machine is the same one, you can skip the pushing step `make docker-push`.
+:::
+
+### Run locally
+
+Building docker image and pushing it to a registry is time-consuming, especially when you are developing and debugging. You can run controller manager locally to accelerate the development process.
+
+:::tip
+In this step, we'll disable webhook validation and run controller manager on the developing machine. The controller manager will communicate with kubernetes cluster by local .kube/config configuration file.
+:::
+
+#### Disable Webhook and CertManager
 
 There are many configuration items that marked by `[CERTMANAGER]` and `[WEBHOOK]` in the two files `config/crd/kustomization.yaml` and `config/default/kustomization.yaml`. They are used to enable and configure webhooks in real kubernetes deployment. Because we want to run controller manager locally, we need to disable them.
 
-You could just apply the latest `deploy/operator.yaml` manifest and delete the following resources to deploy CRDs and make controller manager uninstalled. 
+You could just apply the latest `deploy/operator.yaml` manifest and delete the following resources to deploy CRDs and make controller manager uninstalled.
 
 ```shell
 kubectl delete validatingwebhookconfigurations.admissionregistration.k8s.io oceanbase-validating-webhook-configuration
@@ -19,7 +79,7 @@ kubectl delete -n oceanbase-system svc oceanbase-webhook-service
 kubectl delete -n oceanbase-system deployments.apps oceanbase-controller-manager
 ```
 
-## Self-signed Certificate
+#### Generate Self-signed Certificates
 
 It's necessary for node hosting controller manager to have a TLS certificate. In the real kubernetes cluster, the cert-manager will inject the sign into the controller manager pod. On our laptop, we need self-sign one:
 
@@ -30,9 +90,9 @@ openssl req -new -key /tmp/k8s-webhook-server/serving-certs/tls.key -out /tmp/k8
 openssl x509 -req -days 365 -in /tmp/k8s-webhook-server/serving-certs/tls.csr -signkey /tmp/k8s-webhook-server/serving-certs/tls.key -out /tmp/k8s-webhook-server/serving-certs/tls.crt
 ```
 
-## Run locally
+#### Run ob-operator on Your Machine
 
-There are some useful commands in `Makefile` and `make/*.mk`, we could type `make run-local` to start controller manager locally. Or redirect the output to a log file for better analytic experience, 
+There are some useful commands in `Makefile` and `make/*.mk`, we could type `make run-local` to start controller manager locally. Or redirect the output to a log file for better analytic experience,
 
 ```shell
 # print log to stdout
@@ -41,11 +101,11 @@ make run-local
 make run-local &> bin/run.log
 ```
 
-## Debug locally
+### Debugging
 
 Though print debugging is enough for most cases, there are quite some cases that are not obvious from printed information. We could debug with go debugging tool [delve](https://github.com/go-delve/delve).
 
-`install-delve` command is declared in `make/debug.mk`, we can type `make install-delve` to get it. The help message of it can be glanced, 
+`install-delve` command is declared in `make/debug.mk`, you can type `make install-delve` to get it. The help message of it can be glanced,
 
 ```shell dlv help
 Delve is a source level debugger for Go programs.
@@ -81,13 +141,13 @@ Additional help topics:
   dlv redirect   Help about file redirection.
 ```
 
-## Start debugging
+#### Start delve Debug Server
 
-Run `make run-delve` to start debugging server.
+Run `make run-delve` simply to start debugging server.
 
-### Debug in terminal
+#### Debug in Terminal
 
-If you prefer to debug in terminal, with `dlv connect 127.0.0.1:2345` command you can connect to the debugging server. After connecting, you enter a REPL environment of delve, available commands are showed below, 
+If you prefer to debug in terminal, with `dlv connect 127.0.0.1:2345` command you can connect to the debugging server. After connecting, you enter a REPL environment of delve, available commands are showed below,
 
 ```shell
 (dlv) help
@@ -158,7 +218,7 @@ Other commands:
 Type help followed by a command for full documentation.
 ```
 
-### In VSCode
+#### Debug in VSCode
 
 If you are first to debugging in VSCode, enter `Cmd+Shift+P` to open commands panel. Then, type `Debug: Add Configuration...` and create debugging task for Go. After creating task successfully, open commands panel and type `Debug: Start Debugging`/`Debug: Select and Start Debugging` to start debugging.
 

docsite/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer/contributor-guidance.md

@@ -16,7 +16,7 @@ To get started with developing for our project, please refer to our [Development
 
 ## Deploying Changes
 
-If you are working on changes that require deployment, look at our [Deployment Guide](develop-locally.md) for detailed instructions on how to deploy and test your changes in a production-like environment. This ensures that all changes are vetted for stability and compatibility before being integrated.
+If you are working on changes that require deployment, look at our [Deployment Guide](deploy-locally.md) for detailed instructions on how to deploy and test your changes in a production-like environment. This ensures that all changes are vetted for stability and compatibility before being integrated.
 
 ## How to Contribute