|
| 1 | += Contributing code |
| 2 | + |
| 3 | +:templating-repo: https://github.com/stackabletech/operator-templating |
| 4 | +:operator-repo: https://github.com/stackabletech/operator-rs |
| 5 | +:docker-repo: https://github.com/stackabletech/docker-images |
| 6 | + |
| 7 | +== Development Environment |
| 8 | + |
| 9 | +In order to contribute source code, you need an environment that is capable of running the following tools: |
| 10 | + |
| 11 | +* https://git-scm.com/[Git] |
| 12 | +* https://www.gnu.org/software/make/manual/make.html[make] |
| 13 | +* https://www.docker.com/[Docker] |
| 14 | +* https://kind.sigs.k8s.io/[Kind] |
| 15 | +* https://helm.sh/[Helm] |
| 16 | +* https://kuttl.dev/[Kuttl] |
| 17 | +* https://www.rust-lang.org/[Rust] |
| 18 | +* https://www.python.org/[Python] |
| 19 | +* https://jqlang.github.io/jq/[jq] |
| 20 | +* https://github.com/mikefarah/yq[yq] |
| 21 | +* https://tilt.dev/[Tilt] |
| 22 | +* https://pre-commit.com/[pre-commit] (optional) |
| 23 | + |
| 24 | +Depending on the repository, you might also need https://go.dev/[Go], https://www.java.com/en/[Java] or other programming language support. |
| 25 | + |
| 26 | +Almost all build scripts assume a Unix based environment (preferably Linux). |
| 27 | + |
| 28 | +=== IDEs and Editors |
| 29 | + |
| 30 | +Of course you are free to use whatever works for you best. No editor is perfect but we have positive experience with: |
| 31 | + |
| 32 | +* https://www.jetbrains.com/idea/[IntelliJ Idea] with the `Rust` plug-in |
| 33 | +* https://code.visualstudio.com/[VisualStudio Code] with the `rust-analyzer` extension |
| 34 | + |
| 35 | +For `VisualStudio Code` we also recommend the following extensions: |
| 36 | + |
| 37 | +* https://marketplace.visualstudio.com/items?itemName=tamasfe.even-better-toml[Even Better TOML] |
| 38 | +* https://marketplace.visualstudio.com/items?itemName=vadimcn.vscode-lldb[CodeLLDB] (for debugging) |
| 39 | +* https://marketplace.visualstudio.com/items?itemName=usernamehw.errorlens[Error Lens] (inline error messages) |
| 40 | +* https://marketplace.visualstudio.com/items?itemName=asciidoctor.asciidoctor-vscode[AsciiDoc] |
| 41 | +* https://marketplace.visualstudio.com/items?itemName=GitHub.vscode-pull-request-github[GitHub Pull requests and Issues] |
| 42 | +* https://marketplace.visualstudio.com/items?itemName=eamodio.gitlens[GitLens] |
| 43 | +* https://marketplace.visualstudio.com/items?itemName=ms-python.python[Python] |
| 44 | +* https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-docker[Docker] |
| 45 | + |
| 46 | +== Steps |
| 47 | + |
| 48 | +. Make your desired changes in the according repository and test them manually. Ensure that the code compiles without |
| 49 | + warnings (`cargo clippy --all-targets`) and that the code is formatted with `cargo fmt`. Also make sure that all |
| 50 | + changes are made in accordance to the xref:code-style-guide.adoc[source code style guide]. |
| 51 | +. If code was added or adapted then please create or adapt the unit tests in the same file as well as the integration |
| 52 | + tests in the `tests` directory. Ensure that all unit tests run successfully `cargo test`) and all integration tests |
| 53 | + run successfully (`./scripts/run-tests`). See also <<_changes_in_the_integration_tests>>. |
| 54 | +. Comment your code and check with `cargo doc --document-private-items` that there are no syntax errors. |
| 55 | +. The YAML schemas of the custom resource definitions (CRDs) are rebuilt when the project is compiled (see |
| 56 | + `rust/operator-binary/build.rs` if changing an operator). These CRDs as well as the product configuration are also |
| 57 | + required in the Helm chart and the Kubernetes manifest. To ensure that everything is in a consistent state, please |
| 58 | + execute `make regenerate-charts`. |
| 59 | +. If it is useful for the users of the project to know about the change then it must be added to the changelog. For |
| 60 | + instance, if only the dependencies in an operator are upgraded but nothing changes for the user then the upgrade |
| 61 | + should not be added to the changelog. Conversely, if the dependencies in the {operator-repo}[operator framework] are |
| 62 | + upgraded then changes are probably required in the operators (which are the clients of the framework) and therefore |
| 63 | + the upgrade must be mentioned in the changelog. The changelog must be formatted according to |
| 64 | + https://keepachangelog.com/en/1.1.0/[keep a changelog]. |
| 65 | + |
| 66 | +== Changes in the integration tests |
| 67 | + |
| 68 | +. Most code changes should also be tested with integration tests. The tests for every operator can be found in the |
| 69 | + operator repository in the `tests` directory. |
| 70 | +. Create or adapt the tests. |
| 71 | + Try to mimic the style of the other tests. |
| 72 | + They are written with https://kuttl.dev/[KUTTL] and our own templating tool https://github.com/stackabletech/beku.py[beku.py] to template tests and test multiple product versions at once. |
| 73 | +. Start a test cluster using https://kind.sigs.k8s.io/[kind]. |
| 74 | +. Run your development version of the operator with `make run-dev` (see also xref:testing-on-kubernetes.adoc[] for more information on this). |
| 75 | + This will deploy the operator directly into the cluster, also using part of the Helm Chart definition and therefore the RBAC rules. |
| 76 | +. When making changes to the Helm Chart, you should however test the Helm Chart explicitly. |
| 77 | + First a Docker image of the operator must be built locally and uploaded to the kind cluster and then the Helm chart must be installed. |
| 78 | + This can be achieved in the operator directory with the following commands: |
| 79 | ++ |
| 80 | +[source,bash] |
| 81 | +---- |
| 82 | +docker build --file docker/Dockerfile --tag docker.stackable.tech/stackable/<operator>:<version>-dev . |
| 83 | +kind load docker-image docker.stackable.tech/stackable/<operator>:<version>-dev --name=integration-tests |
| 84 | +helm install <operator> deploy/helm/<operator>/ |
| 85 | +---- |
| 86 | +. Run the tests from the repository root with `./scripts/run-tests`. |
| 87 | + |
| 88 | +== Adding support for a new product version |
| 89 | + |
| 90 | +If a new version of a product was added then the following tasks must be performed: |
| 91 | + |
| 92 | +* Add the new version in the https://github.com/stackabletech/docker-images[docker-images] repository. |
| 93 | +* Update the operator to support the new version if necessary. |
| 94 | +* Update the examples in the operator to use the new version. |
| 95 | +* Update the integration tests. |
| 96 | + The tests should cover the latest patch version of each supported versions. |
| 97 | +* Add the new version to the supported ones in the documentation of the operators (see |
| 98 | + `docs/modules/\{product name\}/partials/supported-versions.adoc` in the operator repositories). |
0 commit comments