Skip to content

Commit

Permalink
docs: Update Contribution Guidelines (opendatahub-io#1266)
Browse files Browse the repository at this point in the history 
Jira Issue: https://issues.redhat.com/browse/RHOAIENG-990
  • Loading branch information
@VaishnaviHire
VaishnaviHire authored Sep 27, 2024
1 parent 4a53076 commit 15dfe1a
Show file tree
Hide file tree
Showing 3 changed files with 104 additions and 45 deletions.
107 changes: 64 additions & 43 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -1,60 +1,81 @@
# Contributing to the Opendatahub Operator

Thanks for your interest in this project. You can contribute to this project in many different ways.
Thanks for your interest in the opendatahub-operator project! You can contribute to this project in various ways: filing bug reports, proposing features, submitting pull requests (PRs), and improving documentation.

## Issues and Enhancements
Before you begin, please take a look at our contribution guidelines below to ensure that your contribuutions are aligned with the project's goals.

Please let us know via our GitHub issue tracker if you find a problem, even if you don't have a fix for it.
The ideal issue report should be descriptive, and where possible include the steps we can take to reproduce the problem for ourselves.
## Reporting Issues
Issues are tracked using [Jira](https://issues.redhat.com/secure/RapidBoard.jspa?rapidView=18680#). If you encounter a bug or have suggestions for enhancements, please follow the steps below:

Please go to [issue tracker](https://github.com/opendatahub-io/opendatahub-operator/issues) and create a "New issue".
Choose suitable issue type and fill in description as detailed as possible.
Lastly, add extra label for this issue if that can help us refine it.
1. **Check for Existing Issues:** Before creating a new issue, search the Jira project to see if a similar issue already exists.
2. **Create a Jira Ticket:** If the issue doesn’t exist, create a new ticket in Jira.
- **For Feature Requests:** Set the issue type to be `Initative`
- **For Bugs:** Set the issue type to `Bug`
- **For all other code changes:** Use the issue type `Story`

If you have a proposed fix for an issue, or an enhancement you would like to make to the code please describe it in an issue, then send us the code as a GitHub pull request as described below.
## Pull Requests

## Pull request
### Workflow

Use a descriptive title, and if it relates to an issue in our tracker please reference which one.
If the PR is not intended to be merged you should prefix the title with "[WIP]" which indicates it is still Work In Progress.
PR's description should provide enough information for a reviewer to understand the changes and their relation to the rest of the code.
1. **Fork the Repository:** Create your own fork of the repository to work on your changes.
2. **Create a Branch:** Create your own branch to include changes for the feature or a bug fix off of `incubation` branch.
3. **Work on Your Changes:** Commit often, and ensure your code adheres to these [Code Style Guidelines](#code-style-guidelines) and passes all the [quality gates](#quality-gates) for the operator.
4. **Testing:** Make sure your code passes all the tests, including any new tests you've added.

## Setting up a Fedora-based development environment
### Open a Pull Request:

This is a loose list of tools to install on your linux box in order to compile, test and deploy the operator.
1. **Link to Jira Issue**: Include the Jira issue link in your PR description.
2. **Description**: Provide a detailed description of the changes and what they fix or implement.
3. **Add Testing Steps**: Provide information on how the PR has been tested, and list out testing steps if any for reviewers.
4. **Review Request**: Tag the relevant maintainers(@opendatahub-io/odh-operator-maintainers ) or team members(@opendatahub-io/odh-platform-members) for a review.
5. **Resolve Feedback**: Be open to feedback and iterate on your changes.

```bash
ssh-keygen -t ed25519 -C "<email-registered-on-github-account>"
# upload public key to github
### Quality Gates

sudo dnf makecache --refresh
sudo dnf install -y git-all
sudo dnf install -y golang
sudo dnf install -y podman
sudo dnf install -y cri-o kubernetes-kubeadm kubernetes-node kubernetes-client cri-tools
sudo dnf install -y operator-sdk
sudo dnf install -y wget
wget https://mirror.openshift.com/pub/openshift-v4/clients/oc/latest/linux/oc.tar.gz
cd bin/; tar -xzvf ../oc.tar.gz ; cd .. ; rm oc.tar.gz
sudo dnf install -y zsh
To ensure the contributed code adheres to the project goals, we have set up some automated quality gates:

# update PATH
echo 'export PATH=${PATH}:~/bin' >> ~/.zshrc
echo 'export GOPROXY=https://proxy.golang.org' >> ~/.zshrc
```
1. [linters](https://github.com/opendatahub-io/opendatahub-operator/blob/incubation/.github/workflows/linter.yaml): Ensure the check for linters is successful. If it fails, run `make lint` to resolve errors
2. [api-docs](https://github.com/opendatahub-io/opendatahub-operator/blob/incubation/.github/workflows/check-file-updates.yaml): Ensure the api-docs are updated when making changes to operator apis. If it fails, run `make generate manifests api-docs` to resolve errors
3. [unit-tests](https://github.com/opendatahub-io/opendatahub-operator/blob/incubation/.github/workflows/unit-tests.yaml): Ensure unit tests pass. Run `make unit-tests`
4. [e2e-tests](https://prow.ci.openshift.org/job-history/gs/test-platform-results/pr-logs/directory/pull-ci-opendatahub-io-opendatahub-operator-incubation-opendatahub-operator-e2e): Ensure CI job for [e2e tests](https://github.com/opendatahub-io/opendatahub-operator/tree/incubation/tests/e2e) pass. Refer run e2e locally to debug. CI test logs can also be found under `Artifacts` directory under Job details.

## Using a local.mk file to override Makefile variables for your development environment
### Code Style Guidelines

To support the ability for a developer to customize the Makefile execution to support their development environment, you can create a `local.mk` file in the root of this repo to specify custom values that match your environment.
1. Follow the Go community’s best practices, which can be found in the official [Effective Go](https://go.dev/doc/effective_go) guide.
2. Follow the best practices defined by the [Operator SDK](https://sdk.operatorframework.io/docs/best-practices/).
3. Use `go fmt` to automatically format your code.
4. Ensure your code passes `make lint` (we have a .golangci.yml file configured in the repo).
5. Ensure you write clear and concise comments, especially for exported functions.
6. Always check and handle errors appropriately. Avoid ignoring errors by using _.
7. Make sure to run `go mod tidy before` submitting a PR to ensure the `go.mod` and `go.sum` files are up-to-date.

```
$ cat local.mk
VERSION=9.9.9
IMAGE_TAG_BASE=quay.io/my-dev-env/opendatahub-operator
IMG_TAG=my-dev-tag
OPERATOR_NAMESPACE=my-dev-odh-operator-system
IMAGE_BUILD_FLAGS=--build-arg USE_LOCAL=true
E2E_TEST_FLAGS="--skip-deletion=true" -timeout 15m
DEFAULT_MANIFESTS_PATH=./opt/manifests
```
### Commit Messages

We follow the conventional commits format for writing commit messages. A good commit message should include:
1. **Type:** `fix`, `feat`, `docs`, `chore`, etc. **Note:** All commits except `chore` require an associated jira issue. Please add link to your jira issue.
2. **Scope:** A short description of the area affected.
3. **Summary:** A brief explanation of what the commit does.

### Testing PR Changes Locally

1. When a PR is opened, we have set up an OpenShift CI job that creates an operator image with the changes - `quay.io/opendatahub/opendatahub-operator:pr-<pr-number>`.
2. Set up your environment to override Makefile defaults as described [here](./docs/troubleshooting.md#using-a-localmk-file-to-override-makefile-variables-for-your-development-environment)
3. Use developer [guide](./README.md#developer-guide) to deploy operator [using OLM](./README.md#deployment) on a cluster.
4. Follow the steps given [here](./README.md#run-e2e-tests) to run e2e tests in your environment.

## Sync Changes in Downstream

After a PR is merged into the upstream `opendatahub-io/opendatahub-operator` repository, the changes need to be synced with the downstream repository:

1. **Cherry-Pick:** Use `git cherry-pick` to apply the changes to the downstream repo ([rhods-operator](https://github.com/red-hat-data-services/rhods-operator)).
2. **Version Labels:** Ensure the downstream PR is labeled with the target release version (e.g., `rhoai-2.14`).
3. **Operator Bundle or Dockerfile Updates:** If changes affect the operator bundle or Dockerfile, sync the changes in the `rhods-cpaas-midstream` repo in addition to downstream PR.

Follow the same [PR Guide](#pull-requests) for creating and reviewing downstream PRs.

## Communication

For general questions, feel free to open a discussion in our repository or communicate via:

- **Slack:** All issues related to ODH platform can be discussed in **#forum-openshift-ai-operator** channel.
- **Jira Comments**: Feel free to discuss issues directly on Jira tickets.
4 changes: 2 additions & 2 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -145,10 +145,10 @@ e.g `make image-build -e IMAGE_BUILD_FLAGS="--build-arg USE_LOCAL=true"`
make image -e IMG=quay.io/<username>/opendatahub-operator:<custom-tag>
```

or (for example to user vhire)
or (for example to user <username>)

```commandline
make image -e IMAGE_OWNER=vhire
make image -e IMAGE_OWNER=<username>
```

The default image used is `quay.io/opendatahub/opendatahub-operator:dev-0.0.1` when not supply argument for `make image`
Expand Down
38 changes: 38 additions & 0 deletions docs/troubleshooting.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -38,3 +38,41 @@ components:
X: {}
```

### Setting up a Fedora-based development environment

This is a loose list of tools to install on your linux box in order to compile, test and deploy the operator.

```bash
ssh-keygen -t ed25519 -C "<email-registered-on-github-account>"
# upload public key to github

sudo dnf makecache --refresh
sudo dnf install -y git-all
sudo dnf install -y golang
sudo dnf install -y podman
sudo dnf install -y cri-o kubernetes-kubeadm kubernetes-node kubernetes-client cri-tools
sudo dnf install -y operator-sdk
sudo dnf install -y wget
wget https://mirror.openshift.com/pub/openshift-v4/clients/oc/latest/linux/oc.tar.gz
cd bin/; tar -xzvf ../oc.tar.gz ; cd .. ; rm oc.tar.gz
sudo dnf install -y zsh

# update PATH
echo 'export PATH=${PATH}:~/bin' >> ~/.zshrc
echo 'export GOPROXY=https://proxy.golang.org' >> ~/.zshrc
```

### Using a local.mk file to override Makefile variables for your development environment

To support the ability for a developer to customize the Makefile execution to support their development environment, you can create a `local.mk` file in the root of this repo to specify custom values that match your environment.

```
$ cat local.mk
VERSION=9.9.9
IMAGE_TAG_BASE=quay.io/my-dev-env/opendatahub-operator
IMG_TAG=my-dev-tag
OPERATOR_NAMESPACE=my-dev-odh-operator-system
IMAGE_BUILD_FLAGS=--build-arg USE_LOCAL=true
E2E_TEST_FLAGS="--skip-deletion=true" -timeout 15m
DEFAULT_MANIFESTS_PATH=./opt/manifests
```

0 comments on commit 15dfe1a

Please sign in to comment.