Skip to content

Latest commit

 

History

History
300 lines (223 loc) · 18.1 KB

CONTRIBUTING.md

File metadata and controls

300 lines (223 loc) · 18.1 KB
Raw

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.

For community-maintained Camunda projects, please visit the Camunda Community Hub. For connectors and process blueprints, please visit Camunda Marketplace instead.

Prerequisites

Contributor License Agreement

You will be asked to sign our Contributor License Agreement 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. By participating, you are expected to uphold this code. Please report 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.

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 that reproduces the problem.

Note

If you have a general usage question, please ask on the 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

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 exists for the task you want to work on. If one does not, create one. Refer to the 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, 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 and Zeebe 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 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.

  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 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, zeebe-client-java, zeebe-gateway-protocol zeebe-gateway-protocol-impl, zeebe-protocol, and zeebe-protocol-jackson which use language level 8.

To quickly build all components for development, run the command: mvn clean install -Dquickly in the root folder.

To build the full distribution for local usage (skipping tests), run the command mvn clean install -DskipChecks -DskipTests.

To fully build and test the Camunda distribution, run the command: mvn 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) by running:

docker build \
  --tag camunda/zeebe:local \
  --build-arg DISTBALL='dist/target/camunda-zeebe*.tar.gz' \
  --target app \
  --file ./camunda.Dockerfile
  .

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).

To run Elasticsearch:

  • Download and unzip 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.

Test execution

Tests can be executed via Maven (mvn verify) or in your preferred IDE. The Zeebe Team uses mostly Intellij IDEA, which we also provide settings for.

Tip

To execute the tests quickly, run mvn 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 #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.

  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 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. 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 merge conflicts, the author of the pull request has to manually rebase main into the issue branch and retrigger a merge attempt.
    3. 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 on how to handle them. Once the CI errors are resolved, a merge can be retried by simply enqueueing the PR again.

Reviewing a pull request

Before doing your first review, please have a look at this guide.

As a reviewer, you are encouraged to use the following 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.

Stale pull requests

If there has not been any activity in your PR after a month, it is automatically marked as stale. If it remains inactive, 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 older versions. We use the backport Github Action to automate this process. Please follow these steps to backport your changes:

  1. Label the pull request with a backport label (e.g. the label backport stable/1.0 indicates that we want to backport this pull request to the stable/1.0 branch).
    • if the pull request is not yet merged, it will be automatically backported when it gets merged.
    • if the pull request is already merged, create a comment on the pull request that contains /backport to trigger the automatic backporting.
  2. The GitHub actions bot comments on the pull request once it finishes:
    • When successful, a new backport pull request was automatically created. Simply approve the PR and enqueue it to the merge queue by clicking the Merge when ready button.
    • If it failed, please follow these manual steps:
      1. Locally checkout the target branch (e.g. stable/1.0).
      2. Make sure it's up to date with the origin (i.e. git pull).
      3. Checkout a new branch for your backported changes (e.g. git checkout -b backport-123-to-stable/1.0).
      4. Cherry-pick your changes git cherry-pick -x <sha-1>...<sha-n>. You may need to resolve conflicts.
      5. Push your cherry-picked changes git push.
      6. Create a pull request for your backport branch:
        • Make sure it is clear that this backports in the title (e.g. [Backport stable/1.0] Title of the original PR).
        • Make sure to change the target of the pull request to the correct branch (e.g. stable/1.0).
        • Refer to the pull request in the description to link it (e.g. backports #123)
        • Refer to any issues that were referenced in the original pull request (e.g. relates to #99).

Commit message guidelines

Commit messages use Conventional Commits format.

<header>
<BLANK LINE> (optional - mandatory with body)
<body> (optional)
<BLANK LINE> (optional - mandatory with footer)
<footer> (optional)

Camunda uses a GitHub Actions workflow to check your commit messages when a pull request is submitted. Please make sure to address any hints from the bot.

Commit message header

Examples:

  • docs: add start event to bpmn symbol support matrix
  • perf: reduce latency in backpressure
  • feat: allow more than 9000 jobs in a single call

The commit header should match the following pattern:

%{type}: %{description}

The commit header should be kept short, preferably under 72 chars but we allow a max of 120 chars.

  • type should be one of:
    • build: Changes that affect the build system (e.g. Maven, Docker, etc)
    • ci: Changes to our CI configuration files and scripts (e.g. GitHub Actions, etc)
    • deps: A change to the external dependencies (was already used by Dependabot)
    • docs: A change to the documentation
    • feat: A new feature (both internal or user-facing)
    • fix: A bug fix (both internal or user-facing)
    • perf: A code change that improves performance
    • refactor: A code change that does not change the behavior
    • style: A change to align the code with our style guide
    • test: Adding missing tests or correcting existing tests
  • description: short description of the change in present tense

Commit message body

Should describe the motivation for the change. This is optional but encouraged. Good commit messages explain what changed AND why you changed it. See I've written a clear changelist description.