CONTRIBUTING.md

Contributing to Zeebe Play

🎉 First off, thanks for taking the time to contribute! 👍

How can I contribute?

Reporting bugs

If you found a bug or an unexpected behevior then please create a new issue. Before creating an issue, make sure that there is no issue yet. Any information you provide in the issue, helps to solve it.

Suggesting enhancements

If you have an idea how to improve the project then please create a new issue. Describe your idea and the motivation behind it.

Please note that this is a community-driven project. The maintainers may have not much time to implement new features if they don't benefit directly from it. So, think about providing a pull request.

Providing a pull requests

You want to provide a bug fix or an improvement? Great! 🎉

Before opening a pull request, make sure that there is a related issue. The issue helps to confirm that the behavior is unexpected, or the idea of the improvement is valid. (Following the rule "Talk, then code")

In order to verify that you don't break anything, you should build the whole project and run all tests. This also apply the code formatting.

Please note that this is a community-driven project. The maintainers may have no time to review your pull request immediately. Stay patient!

Hints for developers

For development, ZeeQS's GraphQL API can be inspected by using http://localhost:8080/graphiql.

Architecture

Contributing to the frontend

The frontend of Zeebe-Play is based on HTML and (plain) JavaScript.

The following libraries are used:

• Bootstrap
• Bootstrap icons
• jQuery
• Thymeleaf (for splitting the HTML page/fragments)
• bpmn-js
• bpmn-font

Enhancing the user interface (UI) or the user experience (UX) are good areas for contributions. But also improvements of the JavaScript code are welcome. Since I don't have much experience in this area, it might look odd and not following best practices.

Update the frontent libraries

• BPMN-JS: download camunda-cloud-navigated-viewer.production.min.js from https://unpkg.com/browse/camunda-bpmn-js/dist/
• DMN-JS: download dmn-navigated-viewer.production.min.js from https://unpkg.com/browse/dmn-js/dist/
• Form-JS: download form-viewer.umd.js from https://unpkg.com/browse/@bpmn-io/form-js/dist/

Contributing to the backend

The backend of Zeebe-Play is written in Kotlin and based on the Spring Boot framework.

Currently, it contains only the REST command API and a few services. The other parts are included from libraries, like the following:

• EZE, runs processes on an embedded Zeebe engine
• ZeeQS, exposes Zeebe's data as a GraphQL API
• Zeebe Hazelcast Exporter, transmits Zeebe's data via Hazelcast
• Zeebe Exporter Protobuf, serializes Zeebe's data to Protobuf

Contributions in the dependent libraries are very welcome and are directly useful for Zeebe-Play.

Building the project from source

You can build the project with Maven.

In the root directory:

Run the tests with

mvn test

Build the JAR files with

mvn clean install

Styleguides

Formatting the source code

The Java code should be formatted using Google's Java Format.

Git commit messages

Commit messages should follow the Conventional Commits format.

For example:

feat: show deployed processes

* query deployed processes from GraphQL
* render query result in process page

Available commit types:

• feat - enhancements, new features
• fix - bug fixes
• refactor - non-behavior changes
• test - only changes in tests
• docs - changes in the documentation, readme, etc.
• style - apply code styles
• build - changes to the build (e.g. to Maven's pom.xml)
• ci - changes to the CI (e.g. to GitHub related configs)