Skip to content

Minimal Reproducer

Jump to bottom
Josh Wulf edited this page May 10, 2024 · 6 revisions

When creating an issue against the C8 JS SDK, you may be asked to provide a minimal reproducer.

What is a minimal reproducer

A minimal reproducer is the smallest implementation that demonstrates the issue you are facing. It is a GitHub repo containing code, and sometimes a BPMN diagram, that demonstrates the issue.

The power of the minimal reproducer

70% of the time, a minimal reproducer will solve the issue you are facing. The act of simplifying the issue down to its essence will isolate and identify any hidden or missed assumptions - you will remove everything else from your scenario except the part you have identified as the issue.

If the issue does not present when you create the smallest possible implementation, it is an indication that the issue lies in the interaction with something that you have not yet identified as the problem.

Many times, while clarifying the issue as a minimal reproducer you may find something that you missed and resolve the issue yourself.

If you end up with a minimal reproducer that demonstrates the issue, then we have a clear expression of the issue in code that serves as a failing test case.

Think of the minimal reproducer as a precisely specified description of the issue in code.

Creating a minimal reproducer may seem like additional effort, but it is a necessary step in solving the issue.

How to create a minimal reproducer

  • You will need an appropriate development environment, with Node.js installed.

  • Please specify the Node version that you are using in your issue report. You can get this with node -v.

  • Please specify the operating system you are using.

  • Create a new GitHub repository for the reproducer and clone it to your machine.

  • Put the following in the .gitignore file:

node_modules
  • Initialise a new project:
npm init -y
  • If you are using TypeScript, initialise a new TypeScript project:
npm i -g typescript && tsc --init
  • Install the C8 JS SDK:
npm i @camunda8/sdk

  • Now create an index.ts (or index.js if you are using JavaScript) and write the code needed to demonstrate the issue you are reporting.

  • Create the smallest possible BPMN model needed to demonstrates your issue.

  • You can run your minimal reproducer with node index.js if it is JavaScript, or with npx ts-node index.ts if it is a TypeScript project.

When you have a minimal implementation that demonstrates your issue:

  • Add any configuration instructions needed to the README.md file, along with the command to run it.

  • Commit the code and push to GitHub.

Examples

The C8 SDK Demo is a minimal example that includes several components and a BPMN process. It is not a reproducer for an issue, but it demonstrates how to build a simple project that involves connecting to Camunda 8.

Clone this wiki locally