# Contributing to Camunda We welcome new contributions. We take pride in maintaining and encouraging a friendly, welcoming, and collaborative community. Anyone is welcome to contribute to Camunda! The best way to get started is to choose an existing [issue](#starting-on-an-issue). For community-maintained Camunda projects, please visit the [Camunda Community Hub](https://github.com/camunda-community-hub). For connectors and process blueprints, please visit [Camunda Marketplace](https://marketplace.camunda.com/en-US/home) instead. - [Prerequisites](#prerequisites) - [Contributor License Agreement](#contributor-license-agreement) - [Code of Conduct](#code-of-conduct) - [GitHub issue guidelines](#github-issue-guidelines) - [Starting on an issue](#starting-on-an-issue) - [Severity and Likelihood (bugs)](#severity-and-likelihood-bugs) - [Build and run Camunda from source](#build-and-run-camunda-from-source) - [Build](#build) - [Run](#run) - [Run via IntelliJ](#run-via-intellij) - [Test execution](#test-execution) - [Test troubleshooting](#test-troubleshooting) - [Build profiling](#build-profiling) - [Creating a pull request](#creating-a-pull-request) - [Reviewing a pull request](#reviewing-a-pull-request) - [Review emoji code](#review-emoji-code) - [Stale pull requests](#stale-pull-requests) - [Backporting changes](#backporting-changes) - [Commit message guidelines](#commit-message-guidelines) - [Commit message header](#commit-message-header) - [Commit message body](#commit-message-body) ## Prerequisites ### Contributor License Agreement You will be asked to sign our [Contributor License Agreement](https://cla-assistant.io/camunda-community-hub/community) when you open a Pull Request. We are not asking you to assign copyright to us but to give us the right to distribute your code without restriction. We ask this of all contributors to assure our users of the origin and continuing existence of the code. > [!NOTE] > In most cases, you will only need to sign the CLA once. ### Code of Conduct This project adheres to the [Camunda Code of Conduct](https://camunda.com/events/code-conduct/). By participating, you are expected to uphold this code. Please [report](https://camunda.com/events/code-conduct/reporting-violations/) unacceptable behavior as soon as possible. ## GitHub issue guidelines If you want to report a bug or request a new feature, feel free to open a new issue on [GitHub][issues]. If you report a bug, please help speed up problem diagnosis by providing as much information as possible. Ideally, that would include a small [sample project][sample] that reproduces the problem. > [!NOTE] > If you have a general usage question, please ask on the [forum][forum]. Every issue should have a meaningful name and a description that either describes: - A new feature with details about the use case the feature would solve or improve - A problem, how we can reproduce it, and what the expected behavior would be - A change and the intention of how this would improve the system ### Severity and Likelihood (bugs): To help us prioritize, please also determine the severity and likelihood of the bug. To help you with this, here are the definitions for the options: Severity: - *Low:* Having little to no noticeable impact on usage for the user (e.g. log noise) - *Mid:* Having a noticeable impact on production usage, which does not lead to data loss, or for which there is a known configuration workaround. - *High:* Having a noticeable impact on production usage, which does not lead to data loss, but for which there is no known workaround, or the workaround is very complex. Examples include issues which lead to regular crashes and break the availability SLA. - *Critical:* Stop-the-world issue with a high impact that can lead to data loss (e.g. corruption, deletion, inconsistency, etc.), unauthorized privileged actions (e.g. remote code execution, data exposure, etc.), and for which there is no existing configuration workaround. - *Unknown:* If it's not possible to determine the severity of a bug without in-depth investigation, you can select unknown. This should be treated as high until we have enough information to triage it properly. Likelihood: - *Low:* rarely observed issue/ rather unlikely edge-case - *Mid:* occasionally observed - *High:* recurring issue #### Determining the severity of an issue Whenever possible, please try to determine the severity of an issue to the best of your knowledge. Only select `Unknown` if it's really difficult to tell without spending a non-negligible amount of time (e.g. >1h) to figure it out. ##### Zeebe heuristic The following is a set of questions which can help determine the severity of a bug in Zeebe: - Was there any data loss or corruption? Then this is **critical**. - Is there a configuration workaround? - Did the cluster recover? By itself, or did it require manual intervention? - Was processing unavailable? - Was exporting unavailable? ### Starting on an issue The `main` branch contains the current in-development state of the project. To work on an issue, follow these steps: 1. Check that a [GitHub issue][issues] exists for the task you want to work on. If one does not, create one. Refer to the [issue guidelines](#github-issue-guidelines). 2. Check that no one is already working on the issue, and make sure the team would accept a pull request for this topic. Some topics are complex and may touch multiple of [Camunda's Components](https://docs.camunda.io/docs/components/), requiring internal coordination. 3. Checkout the `main` branch and pull the latest changes. ``` git checkout main git pull ``` 4. Create a new branch with the naming scheme `issueId-description`. ``` git checkout -b 123-adding-bpel-support ``` 5. Follow the [Google Java Format](https://github.com/google/google-java-format#intellij-android-studio-and-other-jetbrains-ides) and [Zeebe Code Style](https://github.com/camunda/camunda/wiki/Code-Style) while coding. 6. Implement the required changes on your branch and regularly push your changes to the origin so that the CI can run. Code formatting, style, and license header are fixed automatically by running Maven. Checkstyle violations have to be fixed manually. ``` git commit -am 'feat: add BPEL execution support' git push -u origin 123-adding-bpel-support ``` 7. If you think you finished the issue, please prepare the branch for review. Please consider our [pull requests and code reviews](https://github.com/camunda/camunda/wiki/Pull-Requests-and-Code-Reviews) guide, before requesting a review. In general, the commits should be squashed into meaningful commits with a helpful message. This means cleanup/fix etc. commits should be squashed into the related commit. If you made refactorings it would be best if they are split up into another commit. Think about how a reviewer can best understand your changes. Please follow the [commit message guidelines](#commit-message-guidelines). 8. After finishing up the squashing, force push your changes to your branch. ``` git push --force-with-lease ``` ## Build and run Camunda from source We are currently working on [architecture streamlining](https://camunda.com/blog/2024/04/simplified-deployment-options-accelerated-getting-started-experience/) to simplify the deployment and build process. While this is in progress, the build instructions are subject to change. The most recent build instructions will always be in this document. This is a small overview of the contents of this repository: - `authentication` - configures authentication for Camunda 8 - `bom` - bill of materials (BOM) for importing Zeebe dependencies - `build-tools` - Zeebe build tools - `clients` - client libraries - `dist` - provides the Camunda 8 distributions - `identity` - component within self-managed Camunda 8 responsible for authentication and authorization - `licenses` - the Camunda 8 licenses - `monitor` - Monitoring for self-managed Camunda 8 - `operate` - Monitoring tool for monitoring and troubleshooting processes running in Zeebe - `parent` - Parent POM for all Zeebe projects - `qa` - quality assurance for Camunda 8 - `search` - the search clients for Camunda 8 data - `service` - internal services for Camunda 8 - `spring-boot-starter-sdk` - official SDK for Spring Boot - `tasklist` - graphical and API application to manage user tasks in Zeebe - `testing` - testing libraries for processes and process applications - `webapps-common` - shared code between the Camunda 8 web apps - `zeebe` - the process automation engine powering Camunda 8 ### Build > [!NOTE] > All Camunda core modules are built and tested with JDK 21. Most modules use language level 21, exceptions are: camunda-client-java, camunda-process-test-java, zeebe-bpmn-model, zeebe-build-tools, camunda-client-java, zeebe-gateway-protocol zeebe-gateway-protocol-impl, zeebe-protocol, and zeebe-protocol-jackson which use language level 8. * **Quick build:** To **quickly** build all components for development, run the command: `./mvnw clean install -Dquickly` in the root folder. This flag is also used to skip Optimize, when building Camunda. * **Full build:** To build the full distribution for local usage (skipping tests and checks), run the command `./mvnw clean install -DskipChecks -DskipTests`. * **Full build without frontends:** To build the full distribution for local usage without frontends (skipping tests), run the command `./mvnw clean install -DskipChecks -DskipTests -PskipFrontendBuild`. * **Full build and test:** To fully build and test the Camunda distribution, run the command: `./mvnw clean install` in the root folder. If you built a distribution, it can be found in the folder `dist/target`, i.e. ``` dist/target/camunda-zeebe-X.Y.Z-SNAPSHOT.tar.gz dist/target/camunda-zeebe-X.Y.Z-SNAPSHOT.zip ``` This distribution can be containerized with Docker (i.e. build a Docker image) with access to Minimus hardened base images](https://minimus.io/) by running: ``` docker build \ --tag camunda/zeebe:local \ --build-arg DISTBALL='dist/target/camunda-zeebe*.tar.gz' \ --target app \ --file ./camunda.Dockerfile . ``` If you don't have access to [Minimus hardened base images](https://minimus.io/), you can use public base images instead at your own risk by running: ``` docker build \ --tag camunda/zeebe:local \ --build-arg DISTBALL='dist/target/camunda-zeebe*.tar.gz' \ --build-arg BASE_IMAGE='eclipse-temurin:21-jre-noble' \ --build-arg BASE_DIGEST='sha256:20e7f7288e1c18eebe8f06a442c9f7183342d9b022d3b9a9677cae2b558ddddd' \ --target app \ --file ./camunda.Dockerfile . ``` #### Build on macOS with an Apple Silicon chip > [!NOTE] > When building the code on a macOS with a Silicon chip(e.g. M1, etc), the build can fail with protoc errors. If you are running into protoc issues, make sure that you have Rosetta installed locally. Rosetta enables a Mac with Apple silicon to use apps that were built for a Mac with an Intel processor. If you don't have Rosetta installed locally, you can install it with the following command: ``` softwareupdate --install-rosetta --agree-to-license ``` ### Run Operate, Tasklist, and Optimize use Elasticsearch as its underlying data store. Therefore you have to download and run Elasticsearch. (For information on what version of Elasticsearch is needed, refer to the [Supported Environments documentation](https://docs.camunda.io/docs/next/reference/supported-environments/#component-requirements)). To run Elasticsearch: * Download and unzip [Elasticsearch](https://www.elastic.co/downloads/elasticsearch). * For non-production cases, disable Elasticsearch's security packages by setting the `xpack.security.*` configuration options to false in `ELASTICSEARCH_HOME/config/elasticsearch.yml`. * Start Elasticsearch by running `ELASTICSEARCH_HOME/bin/elasticsearch` (macOS/Linux) (or `ELASTICSEARCH_HOME\bin\elasticsearch.bat` on Windows). To start Camunda: * Extract the `dist/target/camunda-zeebe-X.Y.Z-SNAPSHOT.tar.gz` (or `dist/target/camunda-zeebe-X.Y.Z-SNAPSHOT.zip`) distribution package * Run `CAMUNDA_HOME/bin/camunda` (macOS/Linux) (or `CAMUNDA_HOME\bin\camunda.bat` on Windows). If you need to change any of the default configuration values for Camunda, the configuration files are available in `CAMUNDA_HOME/config`. After updating the configuration you need to restart any running services for the changes to take effect. #### Run via IntelliJ You can run the Camunda distribution via IntelliJ for development purposes. 1. Run a **full build** of the project via Maven as [described above](#build). Make sure to use `install` as we need to depend on 2 locally built artifacts. 2. Open the project in IntelliJ. 3. Currently, there is an issue with the `com.auth0.mvc-auth-commons` library being transformed to a Jakarta-compatible version during the Maven build process, but this change not being picked up by IntelliJ. - To address this, open the _Project Structure_ dialog and add the following 2 libraries to the classpath of your JDK (`` being the current snapshot version, e.g. `8.8.0`): - `$HOME/.m2/repository/io/camunda/operate-mvc-auth-commons/-SNAPSHOT/operate-mvc-auth-commons--SNAPSHOT.jar` - `$HOME/.m2/repository/io/camunda/tasklist-mvc-auth-commons/-SNAPSHOT/tasklist-mvc-auth-commons--SNAPSHOT.jar` ![intellij-module-settings.png](docs/assets/intellij-module-settings.png) 4. Start an Elasticsearch instance as [described above](#run). Alternatively, you can start it via Docker from the `operate` directory: ```sh docker compose -f operate/docker-compose.yml up -d elasticsearch ``` 5. Use the provided `StandaloneCamunda DEV` run configuration to start the distribution or create and start a new Spring Boot run configuration with the following settings: - **Module**: `camunda-zeebe` - **Main class**: `io.camunda.application.StandaloneCamunda` - **Active profiles**: `identity,tasklist,operate,broker,consolidated-auth,dev,insecure` - **Environment variables**: ``` ZEEBE_BROKER_EXPORTERS_CAMUNDAEXPORTER_ARGS_CONNECT_URL=http://localhost:9200 ZEEBE_BROKER_EXPORTERS_CAMUNDAEXPORTER_ARGS_INDEX_SHOULDWAITFORIMPORTERS=false ZEEBE_BROKER_EXPORTERS_CAMUNDAEXPORTER_CLASSNAME=io.camunda.exporter.CamundaExporter CAMUNDA_SECURITY_INITIALIZATION_USERS_0_NAME=Demo CAMUNDA_SECURITY_INITIALIZATION_USERS_0_USERNAME=demo CAMUNDA_SECURITY_INITIALIZATION_USERS_0_EMAIL=demo@example.com CAMUNDA_SECURITY_INITIALIZATION_USERS_0_PASSWORD=demo CAMUNDA_SECURITY_INITIALIZATION_DEFAULTROLES_ADMIN_USERS_0_=demo ``` 6. The webapps should be available on the following URLs with the credentials specified above (`demo`/`demo`): - [Tasklist](http://localhost:8080/tasklist) - [Operate](http://localhost:8080/operate) - [Identity](http://localhost:8080/identity) ##### Troubleshooting - If you receive an error on saving the project structure settings regarding the `zeebe-gateway-protocol` not being able to contain the `src/main/proto` directory, fix this by removing the mentioned source root from `zeebe-gateway-protocol` module in the _Modules_ tab. - If you notice errors in files referencing `GatewayOuterClass` (or its inner classes), you may need to increase the maximum file size for which IntelliJ provides code assistance. To do this, `Help -> Edit Custom Properties` and add the following line: `idea.max.intellisense.filesize=9999`. For more details, check https://github.com/camunda/camunda/issues/36041. ### Test execution Tests can be executed via Maven (`./mvnw verify`) or in your preferred IDE. The Zeebe Team uses mostly [Intellij IDEA](https://www.jetbrains.com/idea/), which we also [provide settings for](https://github.com/camunda/camunda/tree/main/.idea). > [!TIP] > To execute the tests quickly, run `./mvnw verify -Dquickly -DskipTests=false`. > The tests will be skipped when using `-Dquickly` without `-DskipTests=false`. #### Test troubleshooting - If you encounter issues (like `java.lang.UnsatisfiedLinkError: failed to load the required native library`) while running the test StandaloneGatewaySecurityTest.shouldStartWithTlsEnabled take a look at https://github.com/camunda/camunda/issues/10488 to resolve it. ### Build profiling The development team continues to push for a performant build. To investigate where the time is spent, you can run your Maven command with the `-Dprofile` option. This will generate a profiler report in the `target` folder. ## Creating a pull request Before opening your first pull request, please have a look at this [guide](https://github.com/camunda/camunda/wiki/Pull-Requests-and-Code-Reviews#pull-requests). 1. To start the review process create a new pull request on GitHub from your branch to the `main` branch. Give it a meaningful name and describe your changes in the body of the pull request. Lastly add a link to the issue this pull request closes, i.e. by writing in the description `closes #123`. Without referencing the issue, our [changelog generation] will not recognize your PR as a new feature or fix and instead only include it in the list of merged PRs. 2. Assign the pull request to one developer to review, if you are not sure who should review the issue skip this step. Someone will assign a reviewer for you. 3. The reviewer will look at the pull request in the following days and give you either feedback or accept the changes. Your reviewer might use [emoji code](#review-emoji-code) during the reviewing process. 1. If there are changes requested, address them in a new commit. Notify the reviewer in a comment if the pull request is ready for review again. If the changes are accepted squash them again in the related commit and force push. Then initiate a merge by adding your PR to the merge queue via the `Merge when ready` button. 2. If no changes are requested, the reviewer will initiate a merge themselves. 4. If there are merge conflicts, the author of the pull request has to [update their pull request by manually rebasing](#updating-a-pull-request). 5. When a merge is initiated, a bot will merge your branch with the latest `main` and run the CI on it. 1. If everything goes well, the branch is merged and deleted and the issue and pull request are closed. 2. If there are CI errors, the author of the pull request has to check if they are caused by its changes and address them. If they are flaky tests, please have a look at this [guide](docs/zeebe/ci.md#determine-flakiness) on how to handle them. Once the CI errors are resolved, a merge can be retried by simply enqueueing the PR again. ## Updating a pull request If there are merge conflicts on a pull request, the author of the pull request has to update it with the latest changes and resolve the conflicts manually. You can do this by rebasing your branch onto the target branch (often `main`) and force push. First fetch the latest changes, and start rebasing on the target branch: ```sh # Example: target is origin/main git fetch origin git rebase origin/main ``` After resolving the conflicts, you can continue the rebase: ```sh git rebase --continue ``` After the rebase is completed, you can force push your branch: ```sh git push --force-with-lease ``` We require rebasing instead of using merge commits to update a pull request to: - keep the history easy to follow, - allow [automated porting of the pull request](#backporting-changes), - and avoid automatically requesting reviews from unrelated users due to [CODEOWNERS](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners). We encourage contributors to regularly rebase their pull requests to minimize the accumulation of merge conflicts. ## Reviewing a pull request Before doing your first review, please have a look at this [guide](https://github.com/camunda/camunda/wiki/Pull-Requests-and-Code-Reviews#code-reviews). As a reviewer, you are encouraged to use the following [emoji code](#review-emoji-code) in your comments. The review should result in: - **Approving** the changes if there are only optional suggestions/minor issues πŸ”§, throughts πŸ’­, or likes πŸ‘.
In cases where ❌ suggestions are straightforward to apply from the reviewers perspective, e.g. "a one-liner"-change for which they don't consider another review needed, the reviewer can pre-approve a PR. This unblocks the author to merge right away when they addressed the required changes. In doubt the author can still decide to require another review, or proactively clarify disagreement with the suggestion. The main point here is that pre-approval puts the author back in charge to make a responsible decision on requiring another review or not and if not get the change merged without further delay. - **Requesting changes** if there are major issues ❌ - **Commenting** if there are open questions ❓ ### Review emoji code The following emojis can be used in a review to express the intention of a comment. For example, to distinguish a required change from an optional suggestion. - πŸ‘ or `:+1:`: This is great! It always feels good when somebody likes your work. Show them! - ❓ or `:question:`: I have a question. Please clarify. - ❌ or `:x:`: This has to change. It’s possibly an error or strongly violates existing conventions. - πŸ”§ or `:wrench:`: This is a well-meant suggestion or minor issue. Take it or leave it. Nothing major that blocks merging. - πŸ’­ or `:thought_balloon:`: I’m just thinking out loud here. Something doesn’t necessarily have to change, but I want to make sure to share my thoughts. _Inspired by [Microsoft's emoji code](https://devblogs.microsoft.com/appcenter/how-the-visual-studio-mobile-center-team-does-code-review/#introducing-the-emoji-code)._ ### Stale pull requests If there has not been any activity in your PR after a month, we may decide to close the PR. When this happens and you're still interested in contributing, please feel free to reopen it. ## Backporting changes Some changes need to be copied to other (often older) versions. We use the [backport](https://github.com/zeebe-io/backport-action) Github Action to automate this process. Please follow these steps to port your changes: 1. **Label the pull request** with a backport label (e.g. the label `backport stable/1.0` indicates that we want to port this pull request to the `stable/1.0` branch). - if the pull request is _not yet_ merged, it will be automatically ported when it gets merged. - if the pull request is _already_ merged, create a comment on the pull request that contains `/backport` to trigger the action. - a pull request can have multiple backport labels, in which case the action ports the pull request to each of those branches. 2. The GitHub actions bot comments on the pull request once it finishes: - When _successful_, a new backport pull request was automatically created. A bot will automatically approve and merge it when it passes the CI. If it doesn't, you'll need to fix the problems and request a new review. - If it _fails_, the action provides instructions in a comment that you need to follow. Once ready, please request a new review. ## Commit message guidelines Commit messages use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/#summary) format. ```
(optional - mandatory with body) (optional) (optional - mandatory with footer)