diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e918b9d08..5ea6b09f7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,8 +1,10 @@ # Contributing to Percona Operator for PostgreSQL +We welcome contributions to the Percona Operator for PostgreSQL project and we're glad that you would like to become a Percona community member and participate in keeping open source open. For you to help us improve the Operator, please follow the guidelines below. + ## Prerequisites -Before submitting code contributions, you should first complete the following prerequisites. +Before submitting code contributions, complete the following prerequisites first. ### 1. Sign the CLA @@ -16,7 +18,7 @@ Please make sure to read and observe the [Contribution Policy](code-of-conduct.m ### 1. Making a bug report -Improvement and bugfix tasks for Percona's projects are tracked in [Jira](https://jira.percona.com/projects/K8SPG/issues). +We track improvement and bugfix tasks for Percona Operator project in [Jira](https://jira.percona.com/projects/K8SPG/issues). Although not mandatory, it is a good practice to examine already open Jira issues first. For bigger contributions, we suggest creating a Jira issue and discussing it with the engineering team and community before proposing any code changes. @@ -24,10 +26,11 @@ Another good place to discuss Percona's projects with developers and other commu ### 2. Contributing to the source tree -Contributions to the source tree should follow the workflow described below: +Follow the workflow described below: + +1. [Fork the repository on GitHub](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo), clone your fork locally, and then [sync your local fork to upstream](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/syncing-a-fork). Make sure to always sync your fork with upstream before starting to work on any changes. -1. First, you need to [fork the repository on GitHub](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo), clone your fork locally, and then [sync your local fork to upstream](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/syncing-a-fork). After that, before starting to work on changes, make sure to always sync your fork with upstream. -2. Create a branch for changes you are planning to make. If there is a Jira ticket related to your contribution, it is recommended to name your branch in the following way: `-`, where the issue number is something like `K8SPG-42`. +2. Create a branch for changes you are planning to make. If there is a Jira ticket related to your contribution, name your branch in the following way: `-`, where the issue number is something like `K8SPG-42`. Create the branch in your local repo as follows: @@ -35,7 +38,7 @@ Contributions to the source tree should follow the workflow described below: $ git checkout -b K8SPG-42-fix-feature-X ``` - When your changes are ready, make a commit, mentioning the Jira issue in the commit message, if any: +3. When your changes are ready, make a commit, mentioning the Jira issue in the commit message, if any: ``` $ git add . @@ -43,13 +46,74 @@ Contributions to the source tree should follow the workflow described below: $ git push -u origin K8SPG-42-fix-feature-X ``` -3. Create a pull request to the main repository on GitHub. -4. When the reviewer makes some comments, address any feedback that comes and update the pull request. -5. When your contribution is accepted, your pull request will be approved and merged to the main branch. +4. Create a pull request to the main repository on GitHub. +5. [Build a custom Operator image based on your changes](#build-a-custom-operator-image) to verify that they work +6. [Update deployment manifests](#update-deployment-manifests) to reflect your changes +7. [Run e2e tests](#run-e2e-tests) to verify your changes are stable and robust. +8. Someone from our team reviews your pull request. When the reviewer makes some comments, address any feedback that comes and update the pull request. +9. When your contribution is accepted, your pull request will be approved and merged to the main branch. + +#### Build a custom Operator image based on your changes + +To build a new Operator image based on your local changes, do the following: + +1. Set the `IMAGE` environment variable to the your image repository and tag. For example: + + ``` + $ export IMAGE=/percona-postgresql-operator: + ``` + + Replace and with your own values. + +2. Build the Docker image and push it to the specified repository: + + ``` + $ make build-docker-image + ``` + +#### Update deployment manifests + +Update the files under the `deploy/` directory to reflect any new fields in the resource API, a new image, etc. The `deploy/` directory contains the CRDs, bundles, and other manifests. + +Run the following command to update deployment manifests: + +``` +$ make generate VERSION= +``` + +`` here is the tag of your built image. + +Next, test your custom changes by deploying the Operator on your Kubernetes cluster. + +First, deploy the Operator: + +``` +$ kubectl apply --server-side -f deploy/bundle.yaml +``` + +Then, deploy a Percona PostgreSQL cluster CRD: + +``` +$ kubectl apply -f deploy/cr.yaml +``` + +#### Run end-to-end tests + +The Operator repository includes a collection of end-to-end (e2e) tests under the `e2e-tests/` directory. You can run these tests on your own Kubernetes cluster to ensure that your changes are robust and stable. + + +To run a specific test by name, use the following command. In the example below, we run the `init-deploy` test: + +``` +$ kubectl kuttl test --config e2e-tests/kuttl.yaml --test "^init-deploy\$" --skip-delete +``` + +Replace `init-deploy` with the name of the test you want to run. ### 3. Contributing to documentation The workflow for documentation is similar, but we store source code for the Percona Operator for PostgreSQL documentation in a [separate repository](https://github.com/percona/k8spg-docs). + See the [Documentation Contribution Guide](https://github.com/percona/k8spg-docs/blob/main/CONTRIBUTING.md) for more information. ### 4. Container images