Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
139 lines (92 loc) · 7.3 KB

CONTRIBUTING.md

File metadata and controls

139 lines (92 loc) · 7.3 KB

Contributing to Scylla Operator

Initial Setup

Fork the repository

Follow GitHub's official documentation on forking a repository.

Development

To add a feature or to make a bug fix, you will need to create a branch in your fork and then submit a pull request (PR) from the branch. A subset of useful commands:

  • make build - build project binaries
  • make test-unit - run unit tests
  • make update - run all code generators
  • make verify - run a preconfigured set of linters and verify that all autogenerated files are up to date

Check make help for more.

Dependencies

Most of the dependencies are managed by Go modules. Some Makefile targets require additional tools to be installed, and it's up to the developer to ensure they are available in the environment:

  • yq
  • jq
  • helm
  • golangci-lint
  • operator-sdk (Note: Until #6978 is merged and released, you need to use operator-sdk from the PR branch; quay.io/scylladb/scylla-operator-images:golang-1.26 image has it preinstalled)
  • ginkgo - for running envtests.
  • podman - for building and running container images.
  • kind - for running local Kubernetes clusters for E2E tests.

Running E2E tests locally

We use Kind for basic local testing. We rely on a kind with rootless Podman setup, so before proceeding, make sure your host system is configured accordingly to Kind Podman rootless guide.

There's a Makefile target to create a Kind cluster with a local registry, build the operator image from local code, and deploy the full operator stack (cert-manager, prometheus-operator, haproxy-ingress, the operator, and scylla-manager).

To set up the Kind cluster and deploy the operator with its dependencies, run:

make kind-setup

make kind-setup is idempotent (that is, can be re-run safely, e.g. to pick up code changes).

You can skip building the operator image by setting the SO_IMAGE environment variable:

SO_IMAGE="quay.io/scylladb/scylla-operator:latest" make kind-setup

When you define SO_IMAGE explicitly, please note that the image must be accessible from within the Kind cluster:

  • If you're using a public image, make sure it's pushed to a public registry and that the cluster has access to it (it should work out of the box for quay.io).
  • If you're using a locally built image, you should tag it with localhost:5001/your-image-name:tag and push it to the local registry: podman push --tls-verify=false localhost:5001/your-image-name:tag. If you don't define SO_IMAGE, the image built from local code will be automatically loaded into the Kind cluster, so you don't need to worry about pushing it.

You can then run the E2E tests (kind-fast suite) with:

make test-e2e-kind

The tests will run against the Kind cluster created in the previous step. A pod running the tests will be created in the e2e namespace.

To run specific test cases, use the SO_FOCUS environment variable (it accepts a regexp filtering ginkgo test cases). For example:

SO_FOCUS=".*TestCaseName.*" make test-e2e-kind

If you ever need to start from a clean state, you can delete the Kind cluster with:

make kind-teardown

Coding convention

Follow these guidelines for writing and structuring your code:

In cases where the existing code doesn't fully follow these conventions, try to be consistent with what's already there. Make sure to familiarize yourself with these resources before making changes.

Enhancement proposals

For significant features or API changes, you might be required to prepare an enhancement proposal beforehand, as these usually involve broader discussions. If unsure, please consult the maintainers of the project to learn if your contribution falls into these categories before you start working on the implementation.
For further details, see Enhancement Proposals directory.

Submitting a Pull Request

Once you have implemented the feature or bug fix in your branch, open a PR to the upstream repository. Before doing so, ensure the following:

  • Unit tests are included.
  • End-to-end tests are passing.
  • Your commit history is clean.
  • Your commit message and PR title follow the guidelines outlined in this section.
  • If your changes are user-facing, you have added an appropriate entry to the changelog.

Commit History

To maintain a clean commit history, aim for a minimal number of logical commits. Typically, this means a single commit that contains all the changes, with a separate commit for autogenerated parts.

Commits and PRs

We follow Conventional Commits for all commit messages and PR titles.

Changelog entries

If your changes are user-facing (new features, bug fixes, behavior changes, deprecations, or breaking changes), add an entry to the CHANGELOG.md in the Unreleased section. Link to your PR using the format [#1234](https://github.com/scylladb/scylla-operator/pull/1234). The entry should describe the change from the user's perspective, not implementation details.

If multiple PRs are working together to deliver a single feature from the user's perspective, it's advised to group them as a single entry in the changelog.

Internal refactoring, test improvements, and CI changes typically don't require changelog entries unless they significantly impact users.

Code review

Refer to The Standard of Code Review for best practices when conducting peer reviews or responding to feedback.

Submitting

After addressing the review feedback, squash your changes into the original commits. Avoid adding new commits. Your PR should always be in a mergeable state.

Maintenance

Configuring Renovate

We're using Renovate for automatic dependency updates of some components. If you want to modify Renovate's configuration, edit the renovate.json file in the repository root. You can verify your changes by running Renovate locally using the following command: ./hack/check-renovate.sh. If there are any updates that you expect Renovate to make, but the script does not report them, please adjust your configuration accordingly.