open-cluster-management/CONTRIBUTING.md

**Table of Contents**

- [Contributing guidelines](#contributing-guidelines)
  - [Terms](#terms)
  - [Certificate of Origin](#certificate-of-origin)
  - [DCO Sign Off](#dco-sign-off)
  - [Code of Conduct](#code-of-conduct)
  - [Contributing a patch](#contributing-a-patch)
  - [Setting up your dev environment, coding, and debugging](#setting-up-your-dev-environment-coding-and-debugging)
    - [Prerequisites](#prerequisites)
    - [Setting up dev environment](#setting-up-dev-environment)
    - [Building Images](#building-images)
    - [Making changes to the API and CRDs](#making-changes-to-the-api-and-crds)
    - [Testing the changes in the kind cluster](#testing-the-changes-in-the-kind-cluster)
    - [Integration tests](#integration-tests)
    - [E2E tests](#e2e-tests)
  - [Issue and pull request management](#issue-and-pull-request-management)
- [References](#references)

# Contributing guidelines

The ocm repo contains 5 core components:
* registration
* placement
* work
* registration-operator
* addon-manager

## Terms

All contributions to the repository must be submitted under the terms of the [Apache Public License 2.0](https://www.apache.org/licenses/LICENSE-2.0).

## Certificate of Origin

By contributing to this project, you agree to the Developer Certificate of Origin (DCO). This document was created by the Linux Kernel community and is a simple statement that you, as a contributor, have the legal right to make the contribution. See the [DCO](DCO) file for details.

## DCO Sign Off

You must sign off your commit to state that you certify the [DCO](DCO). To certify your commit for DCO, add a line like the following at the end of your commit message:

```
Signed-off-by: John Smith <john@example.com>
```

This can be done with the `--signoff` option to `git commit`. See the [Git documentation](https://git-scm.com/docs/git-commit#Documentation/git-commit.txt--s) for details.

## Code of Conduct

The Open Cluster Management project has adopted the CNCF Code of Conduct. Refer to our [Community Code of Conduct](CODE_OF_CONDUCT.md) for details.

## Contributing a patch

1. Submit an issue describing your proposed change to the repository in question. The repository owners will respond to your issue promptly.
2. Fork the desired repository, then [develop and test](#setting-up-your-dev-environment-coding-and-debugging) your code changes.
3. Submit a pull request.

## Setting up your dev environment, coding, and debugging

### Prerequisites

- [Golang](https://go.dev/doc/install)
- Container Engin: [Docker](https://docs.docker.com/engine/install/) or [Podman](https://podman.io/docs/installation)
- [Kind](https://kind.sigs.k8s.io/docs/user/quick-start/#installation)
- [kubectl](https://kubernetes.io/docs/tasks/tools/)

### Setting up dev environment

For development purposes, we can use the [kind](https://kind.sigs.k8s.io/docs/user/quick-start/#installation) tool to
create a local Kubernetes cluster and deploy the Open Cluster Management components.

1. Create a kind cluster:

```bash
kind create cluster
```

2. Deploy the Open Cluster Management components referring to the [Setup hub and managed clusters](https://open-cluster-management.io/getting-started/quick-start) guide on the kind cluster created in the previous step. Summary the key steps are:

    1. Install the clusteradm CLI tool:
    ```bash
    curl -sL https://raw.githubusercontent.com/open-cluster-management/clusteradm/main/hack/install.sh | bash
    ```
    2. Init the control plane:
    ```bash
    clusteradm init --wait --bundle-version="latest"
    ```
    3. Join the hub cluster as a managed cluster(self management):
    ```bash
    clusteradm join --hub-token <hub-token> --hub-apiserver <hub-apiserver> --wait --cluster-name cluster1 --force-internal-endpoint-lookup --bundle-version="latest"
    ```
    4. Access the hub cluster:
    ```bash
    clusteradm accept --clusters cluster1
    ```

3. Check the Open Cluster Management components are running:

```bash
╰─# kubectl get clustermanager cluster-manager
NAME              AGE
cluster-manager   7h36m

╰─# kubectl get managedcluster
NAME       HUB ACCEPTED   MANAGED CLUSTER URLS              JOINED   AVAILABLE   AGE
cluster1   true           https://kind-control-plane:6443   True     True        7h36m

╰─# kubectl get deployment -A | grep open-cluster-management
open-cluster-management-agent   klusterlet-registration-agent             # register the managed cluster
open-cluster-management-agent   klusterlet-work-agent                     # distribute resources to the managed cluster
open-cluster-management-hub     cluster-manager-addon-manager-controller  # manage the addons
open-cluster-management-hub     cluster-manager-placement-controller      # manage the placement
open-cluster-management-hub     cluster-manager-registration-controller   # manage the registration
open-cluster-management-hub     cluster-manager-registration-webhook      # validate managedcluster/managedclusterset
open-cluster-management-hub     cluster-manager-work-webhook              # validate manifestwork
open-cluster-management         cluster-manager                           # watch clustermanager and deploy the hub components
open-cluster-management         klusterlet                                # watch managedcluster and deploy the managed cluster components
```

Note: if klustelet is deployed in Singleton mode(`clusteradm join --hub-token <hub-token> --hub-apiserver <hub-apiserver> --wait --cluster-name cluster1 --force-internal-endpoint-lookup --bundle-version="latest" --singleton=true`), the `klusterlet-registration-agent`
 and `klusterlet-work-agent` will be replaced by one deployment `klusterlet-agent`.

Once the Open Cluster Management components are deployed, you can start developing and testing your changes.

### Building Images

There are 5 core images that are built from the ocm repository: `registration`, `placement`, `work`,
`registration-operator`, and `addon-manager`.

To build all these images, you can run the following command:

```bash
# Replace the IMAGE_REGISTRY and IMAGE_TAG with your desired values
IMAGE_REGISTRY=quay.io/open-cluster-management IMAGE_TAG=test make images
```

To build a specific image, you can run the following command:

```bash
# the <image-name> can be one of the following: registration, placement, work, registration-operator, addon-manager
IMAGE_REGISTRY=quay.io/open-cluster-management IMAGE_TAG=test make image-<image-name>
```

After building the images, you can push them to the registry by docker/podman push, if you do not have a registry,
 you can use the command `kind load docker-image quay.io/open-cluster-management/<image-name>:test` to load the
  images into the kind cluster.

### Making changes to the API and CRDs

In order to change Custom Resource Definitions and the API in [ocm](https://github.com/open-cluster-management-io/ocm), one needs to make changes to the [api](https://github.com/open-cluster-management-io/api) repository and then use them in the [ocm](https://github.com/open-cluster-management-io/ocm) repository. This section aims to walk you through these steps with an example.


1. Clone a fork of both ocm and api to your machine
    ```shell
    git clone git@github.com:<your-username>/api.git
    git clone git@github.com:<your-username>/ocm.git
    ```

2. Make your API changes
   
    Make your changes in your api repository. For example, let's say you wanted to change the `ClientCertExpirationSeconds` to be `ClientCertExpirationMinutes` for some reason:


    ```go
    type RegistrationConfiguration struct {
      // clientCertExpirationMinutes represents the minutes of a client certificate to expire. If it is not set or 0, the default
      // duration minutes will be set by the hub cluster. If the value is larger than the max signing duration minutes set on
      // the hub cluster, the max signing duration minutes will be set.
      // +optional
      ClientCertExpirationMinutes int32 `json:"clientCertExpirationMinutes,omitempty"`
        ...
    ```
    In your api repository, run the following to generate CRDs and DeepCopy functions
    ```shell
    user@fedora:~/api$ make update
    ```

    You'll notice that a few files such as `operator/v1/zz_generated.deepcopy.go` and `operator/v1/0000_00_operator.open-cluster-management.io_klusterlets.crd.yaml` have been changed to reflect the changes in the API and CRD.
3. Sync API updates with ocm repository

    In order to use the new API, you'll have to sync them to your ocm repository. In your ocm repository, go to your go.mod file and replace `open-cluster-management.io/api` with your own updated version. This can be done by using the `replace` directive. At the end of the go.mod file, add:

    ```go
    go mod edit -replace open-cluster-management.io/api=/home/<user>/api #path to my local api repo w/ changes
    ```

    _Note: Only use the replace directive during development/debugging. Make sure to remove it before making a PR to [ocm](https://github.com/open-cluster-management-io/ocm) and once changes to the upstream [api repo](https://github.com/open-cluster-management-io/api) are merged._

    Then, in your ocm repository, run the following:
    ```shell
    user@fedora:~/ocm$ go mod tidy
    user@fedora:~/ocm$ go mod vendor
    user@fedora:~/ocm$ make update
    ```

### Testing the changes in the kind cluster

After building and pushing the images, you can test the changes in the kind cluster.

1. Test the operators(deployment `cluster-manager` or `klusterlet` in the `open-cluster-management` namespace) changes
by replacing the registration-operator image for the operators deployments:

```bash
kubectl set image -n open-cluster-management deployment/cluster-manager registration-operator=$(IMAGE_REGISTRY)/registration-operator:$(IMAGE_TAG)
kubectl set image -n open-cluster-management deployment/klusterlet klusterlet=$(IMAGE_REGISTRY)/registration-operator:$(IMAGE_TAG)
```

2. Test the hub side components changes by replacing the image fields in the clustermanager spec:

```bash
kubectl edit clustermanager cluster-manager
```

3. Test the managed cluster side components changes by replacing the image fields in the klusterlet spec:

```bash
kubectl edit klusterlet klusterlet
```

### Integration tests

The integration tests are written in the [test/integration](test/integration) directory. They start a kubernetes
api server locally with [controller-runtime](https://book.kubebuilder.io/reference/envtest), and run the tests against
the local api server.

To run the integration tests, you can use the following command:

```bash
make test-integration # run all the integration tests
make test-<component>-integration # run the integration tests for a specific component
```

### E2E tests

The E2E tests are written in the [test/e2e](test/e2e) directory. You can run the E2E tests:
- referring to the steps described in the [e2e workflow](.github/workflows/e2e.yml) file
- or by the [act](https://github.com/nektos/act) command: `act -j e2e`

## Issue and pull request management

Anyone can comment on issues and submit reviews for pull requests. In order to be assigned an issue or pull request, you can leave a `/assign <your Github ID>` comment on the issue or pull request.

# References

Please refer to [the Contribution Guide](https://open-cluster-management.io/contribute/)