Contributing
Setup, quality gates, tests and pull request rules. The structure of the code is on Architecture, publishing on Releasing, the reasons behind the design in the Architecture Decisions.
Setup
You need Java 21 (.java-version) and, for the pre-push hook, Lefthook:
brew install lefthook # macOS; other platforms: see the Lefthook installation guide
lefthook installOptional: a .NET 8 SDK (or a container that provides dotnet and Java 21) for the C# tests in packages/nuget, and Node 22 for the docs site, the BPMN linter and the TypeScript tests in packages/npm.
Everyday commands
./gradlew build # everything CI builds: compile, ktlint, detekt, all tests
./gradlew :bpmn-to-code-core:test # tests of one module
./gradlew lintKotlin # ktlint check
./gradlew formatKotlin # ktlint auto-fix
./gradlew detektMain detektTest # detekt with type resolution
./gradlew :bpmn-to-code-core:test :bpmn-to-code-core:jacocoTestCoverageVerification # coverage ruleQuality gates
| Gate | Command | Rule |
|---|---|---|
| ktlint | ./gradlew lintKotlin | Formatting and imports, configured in .editorconfig. Lines target 120 characters; the hard line-length rule is off. |
| detekt | ./gradlew detektMain detektTest | Configured in config/detekt/detekt.yml with maxIssues: 0. Plain detekt runs without type resolution and can pass where CI fails. |
| Architecture | ./gradlew :bpmn-to-code-architecture-tests:test | Konsist tests for the layers of core, the imports allowed to the other modules, naming per layer, and one top-level type per file. See Architecture. |
| Coverage | ./gradlew :<module>:test :<module>:jacocoTestCoverageVerification | At least 75 % line coverage per class. CI verifies core, web, testing and runtime; each module's build file lists the classes it leaves out. |
| Mutation testing | ./gradlew :<module>:pitest --no-configuration-cache | PIT mutation score of at least 80 for core, 90 for web, 95 for runtime and testing. |
| BPMN lint | npm --prefix tools run lint:bpmn | bpmnlint over the shared models, see tools/README.md. |
There is no baseline and no suppression list for ktlint or detekt: fix the finding, or add a scoped exception to the config with a comment that says why. The exceptions that exist today: ktlint allows wildcard imports for Ktor, and both tools skip the checked-in generated example inside bpmn-to-code-runtime.
What runs where
| Pre-push hook | Pull request | Nightly | |
|---|---|---|---|
compileKotlin | yes | yes | |
| ktlint, detekt | yes | yes | |
| All tests (incl. architecture tests) | yes | ||
C# and TypeScript tests in packages/ | yes, in build-packages.yml | ||
| Coverage rule | core only, see below | core, web, testing, runtime | |
| PIT | core, runtime, web, testing | ||
| Docs build | when docs/ changed | ||
| BPMN lint | when a .bpmn file or tools/ changed |
The hook only runs when the push contains .kt or .kts files, and the Gradle jobs in CI only run when a module or the build setup changed. The hook does not run the tests: its coverage step checks whatever test results are already in build/, so run the tests yourself before pushing. git push --no-verify skips the hook; CI still enforces everything.
PIT is too slow for a pull request. It runs every night and on demand (gh workflow run mutation-testing.yml) and fails when a module drops below its threshold.
Tests
Shared models. shared/bpmn/{c7,zeebe,operaton} holds the MiraVelo processes once per engine. The folder is a test resource root of core, gradle, maven, web and testing, so tests load /bpmn/zeebe/bike-leasing.bpmn. The web app bundles the bike-leasing models as its examples and the benchmark uses them as input. They follow the modeling guide and are linted in CI. Deliberately broken models live in the test resources of the module that needs them, not here.
In-memory models. Tests that do not exercise BPMN reading build their model in code, with the builders in core's test sources under io.miragon.bpmn.domain: testProcessModel() and testProcessModelApi() for a small model with defaults, testBikeLeasingModel() and testCancelBikeOrderModel() as mirrors of the shared models, jobWorkerTask() for a single node.
Golden files. Builder tests compare the generated text byte for byte with files under bpmn-to-code-core/src/test/resources/api. After an intended change, rewrite them and review the diff:
./gradlew :bpmn-to-code-core:test -Dgolden.update=trueThe flag also updates the generated bike-leasing API checked in under bpmn-to-code-runtime/src/test. The runtime cannot depend on core, so its ProcessPath tests run against that copy, and RuntimeExampleDriftTest in core fails when copy and golden file differ.
Compiled output. Core's tests compile the generated Kotlin with the embedded Kotlin compiler and the generated Java with javac. Core only compares the generated C# and TypeScript with golden files and needs neither toolchain. Whether that output compiles against its runtime package is tested next to the package, on code the command-line tool generates, the way a user's build does. Both test suites take the tool from ./gradlew :bpmn-to-code-cli:installDist, or from the path in BPMN_TO_CODE_CLI, and fail when it is missing.
packages/nuget/BpmnToCode.Runtime.Tests is an xUnit project. Before it compiles, it generates the bike-leasing and nested-subprocess APIs and walks them with ProcessPath. Further cases generate into a temporary directory and are compiled in memory with Roslyn, as C# 12 with warnings as errors:
./gradlew :bpmn-to-code-cli:installDist
dotnet test packages/nuget/BpmnToCode.Runtime.TestsThe tests start the tool, which runs on Java, so dotnet and Java 21 have to be available in the same environment. Without a local .NET 8 SDK, use an image that has both:
FROM docker.io/library/eclipse-temurin:21-jdk AS jdk
FROM mcr.microsoft.com/dotnet/sdk:8.0
COPY --from=jdk /opt/java/openjdk /opt/java/openjdk
ENV JAVA_HOME=/opt/java/openjdk PATH=/opt/java/openjdk/bin:$PATHpodman build -t dotnet8-jdk21 -f Containerfile . # the file above
podman run --rm -v "$PWD":"$PWD" -w "$PWD" dotnet8-jdk21 dotnet test packages/nuget/BpmnToCode.Runtime.Testsnpm test in packages/npm/bpmn-to-code-runtime builds the runtime package and generates several models into test/generated. It then type-checks them with tsc --strict together with consumer code, once with nodenext and once with bundler module resolution, and runs the process path scenarios with Node:
./gradlew :bpmn-to-code-cli:installDist
npm ci --prefix packages/npm/bpmn-to-code-runtime
npm test --prefix packages/npm/bpmn-to-code-runtimeOther layers. The Gradle module runs smoke tests with Gradle TestKit, the Maven module executes its mojos directly, and the web module tests its routes with the Ktor test host. Unit test conventions are in the create-unit-test skill under .claude/skills/.
Pull requests
- The PR title must be a Conventional Commit with one of the types
feat,fix,chore,docs,refactor,ci,build,test,revert, for examplefix(runtime): leave the compensation boundary event out of a process path. If the PR has a single commit, that commit message is checked the same way. - release-please builds the changelog and the next version number from these titles once they are on
main, so afeatorfixtitle is what users read in the release notes. - Update golden files together with the generator change that causes them, see Tests.
- A feature behaves the same in the Gradle plugin, the Maven plugin, the web app and core.
- Examples in code, tests and docs use the MiraVelo models from
shared/bpmn.
Docs site
The site is VitePress in docs/, built with the Miragon docs kit in docs/.vitepress/miragon/. The kit is vendored unchanged from Miragon/corporate-identity (skill docs-site) and sets theme, colours in light and dark mode, anchors, Mermaid, search and the legal row; node .vitepress/miragon/check.mjs fails when it was edited here. The repo only owns config.ts, the landing page in theme/ and the pages:
cd docs
npm ci
DOCS_BASE=/bpmn-to-code/ npm run build # what CI runs; fails on dead links
npx vitepress dev # local preview with hot reloadnpm run dev is the maintainer's shortcut and needs the portless CLI and macOS. The site is deployed to GitHub Pages as part of a release, see Releasing.
Design and wording
The docs site and the web app follow the Miragon corporate design:
- Colours, spacing and radii come from
cd-tokens.generated.css: for the docs it ships with the kit, the web app keeps its own copy instatic/css/. The file is generated from the Miragon design tokens. Replace it as a whole when the tokens change and never edit it by hand. Stylesheets use the--cd-ui-*roles instead of raw colour values. - The typefaces are Geist and Geist Mono, shipped with the site and the app.
- Text stays English, because bpmn-to-code is used internationally. Apart from that the Miragon writing rules apply: no dash as a connector between clauses, no emoji as decoration, concrete statements instead of adjectives.
- One name per thing: "Agent Skills", "CIB seven", "Camunda 7", "Camunda 8".
Maintainers with the miragon-brand Claude Code plugin get these rules checked on every edit through .miragon/brand.json.
Agent tooling
CLAUDE.md(AGENTS.mdis a symlink to it) holds the instructions for coding agents;.claude/rules/holds the Kotlin style rules..claude/skills/holds the skills for working on this repository:create-unit-testandbpmn-to-code-validate-docs. Add one as.claude/skills/<name>/SKILL.mdwithnameanddescriptionfrontmatter.bpmn-to-code-skills/is a product: the Claude Code plugin shipped to users of bpmn-to-code, documented under Agent Skills. Changes there are user-facing.