Merge branch 'main' into check-anchors

.github/workflows/check-versions.yaml

@@ -1,25 +1,22 @@
 name: Check versions
 
-on: pull_request_target
+on: pull_request
 
 jobs:
   list-pr-changes:
     runs-on: ubuntu-latest
     steps:
-      - name: Checkout PR branch
+      - name: Checkout last two commits of the PR
+        # The last *two* commits are (1) everything in this branch, and (2) the parent of this branch.
         uses: actions/checkout@v3
         with:
-          ref: ${{ github.event.pull_request.head.sha }}
-          fetch-depth: 0
-
-      - name: Fetch target base (what we're merging into)
-        run: git fetch origin ${{ github.event.pull_request.base.ref }}
+          fetch-depth: 2
 
       - name: Capture version configuration as environment variable
         run: echo "VERSION_CONFIG=$(jq -c . < .github/workflows/check-versions/version-config.json)" >> $GITHUB_ENV
 
       - name: Capture changed files as environment variable
-        run: echo "CHANGED_FILES=$(git diff --name-only HEAD..FETCH_HEAD | jq -R -s -c 'split("\n")[:-1]')" >> $GITHUB_ENV
+        run: echo "CHANGED_FILES=$(git diff --name-only HEAD^ | jq -R -s -c 'split("\n")[:-1]')" >> $GITHUB_ENV
 
       - name: Identify missing changes
         id: identify-missing-changes

docs/apis-tools/build-your-own-client.md

@@ -71,10 +71,10 @@ export ACCESS_TOKEN=$(curl -s --request POST \
   --data "{\"client_id\":\"${ZEEBE_CLIENT_ID}\",\"client_secret\":\"${ZEEBE_CLIENT_SECRET}\",\"audience\":\"${ZEEBE_TOKEN_AUDIENCE}\",\"grant_type\":\"client_credentials\"}" | sed 's/.*access_token":"\([^"]*\)".*/\1/' )
 ```
 
-4. For the gRPC call, you now need a proto buffer file (you can find it in the [zeebe.io repository](https://raw.githubusercontent.com/camunda-cloud/zeebe/develop/gateway-protocol/src/main/proto/gateway.proto)):
+4. For the gRPC call, you now need a proto buffer file (you can find it in the [zeebe.io repository](https://raw.githubusercontent.com/camunda/zeebe/main/zeebe/gateway-protocol/src/main/proto/gateway.proto)):
 
 ```bash
-curl -sSL https://raw.githubusercontent.com/camunda-cloud/zeebe/develop/gateway-protocol/src/main/proto/gateway.proto > /tmp/gateway.proto
+curl -sSL https://raw.githubusercontent.com/camunda/zeebe/main/zeebe/gateway-protocol/src/main/proto/gateway.proto > /tmp/gateway.proto
 ```
 
 5. Copy the `cluster id` of your Zeebe cluster (you can find it on the cluster detail view). Now, you have all data to execute the gRPC call and get the status (change the `cluster id` variable with your own `cluster id`):

docs/apis-tools/tasklist-api-rest/migrate-to-zeebe-user-tasks.md

@@ -28,6 +28,10 @@ In this guide, you will learn:
 - How to estimate the impact on a project.
 - The steps you need to take for a successful migration without interrupting your operations.
 
+:::info
+The [Zeebe-based user task implementation](/components/modeler/bpmn/user-tasks/user-tasks.md) is not yet supported in the user interface in version 8.5-alpha2, and ignored in search result sets. However, they can be accessed via the API. To use the Tasklist user interface, use the [job worker-based implementation](/components/modeler/bpmn/user-tasks/user-tasks.md#job-worker-implementation).
+:::
+
 ## Decide on your migration path
 
 Zeebe user tasks require migration of the user tasks in both your diagrams and the task API.

docs/components/best-practices/architecture/deciding-about-your-stack.md

@@ -9,83 +9,84 @@ tags:
   - Maven
 ---
 
-If you don't have special architecture requirements, we recommend using SaaS following the proposed greenfield stack.
-
 :::caution Camunda 8
-This best practice targets Camunda 8 only! If you look for Camunda 7, please refer to [Deciding about your Camunda 7 stack](../deciding-about-your-stack-c7/).
+This best practice targets Camunda 8. For Camunda 7, please refer to [Deciding about your Camunda 7 stack](../deciding-about-your-stack-c7/).
 :::
 
-## The greenfield stack
+Our greenfield stack recommendation is a result of extensive discussions and evaluations. While not the only option, it is a solid choice if there are no specific reasons to choose an alternative.
 
-We like to give one greenfield stack recommendation, which is the stack you can simply use if there is no reason against it. And while we went through long and detailed discussions to come to this recommendation, it _doesn't_ mean that it is necessarily superior to alternative stacks. You can still feel confident if you go down another route (note below for alternative options).
+Your choice of programming language should align with your team's expertise; we suggest Java or JavaScript for their broad applicability and support, and have outlined the Java greenfield stack below with Camunda 8 SaaS.
 
-The stack looks pretty similar in various programming language. Please use the programming language your team is most familiar with. If in doubt, use Java or JavaScript.
+## The Java greenfield stack
 
-### The Java greenfield stack
+:::caution
+[Spring Zeebe](https://github.com/camunda-community-hub/spring-zeebe) is currently a community-maintained project.
+:::
 
 ![greenfield stack architecture diagram](deciding-about-your-stack-assets/greenfield-architecture.png)
 
-Use the following stack:
+This architecture diagram illustrates the flow of requests from a user's browser through Camunda SaaS, where workflows and decisions are orchestrated. The process then moves to the Spring Boot application, which is responsible for executing business logic, handling database interactions with PostgreSQL, and managing various components such as custom REST endpoints, BPMN/DMN definitions, and external task workers.
 
-1. Use [Camunda 8 SaaS](https://signup.camunda.com/accounts?utm_source=docs.camunda.io&utm_medium=referral) and create a cluster there
+### Why this stack?
 
-1. Build your process solution project as a [Spring Boot](https://spring.io/projects/spring-boot) application, using the [Spring Zeebe](/docs/apis-tools/community-clients/spring.md).
+- SaaS simplifies workflow engine integration.
+- Spring Boot is widely adopted for Java application development.
+- Flexible for both on-premise and cloud environments.
 
-1. Use [Maven](https://maven.apache.org/) as a build tool.
+Discover more in our [getting started guide for microservices orchestration](/guides/getting-started-orchestrate-microservices.md) or the [Spring Zeebe instructions](https://github.com/camunda-community-hub/spring-zeebe).
 
-1. Use your favorite IDE, for example Visual Studio Code, IntelliJ or Eclipse.
+### Set up the stack
 
-1. Use [Open JDK 17](https://jdk.java.net/17/) as Java runtime.
+For a Java-based setup using Camunda 8 SaaS and Spring Boot, use the following stack:
 
-1. Model the processes with the [Camunda Modeler](https://camunda.org/download/modeler/).
+#### Camunda 8 SaaS account and cluster
 
-1. Add your process models and all Java code to the project.
+If you're new to Camunda SaaS, check out our [getting started guide](/guides/introduction-to-camunda-8.md#getting-started) to set up your environment.
 
-To run the process application _in production_:
+After signing up, create a cluster by following [creating a cluster in Camunda 8](/guides/create-cluster.md), which provides step-by-step instructions on setting up a new cluster in the Camunda 8 environment.
 
-3. Run the process application by copying the `jar` file to the server and start it with `java -jar YourProcessApplication.jar`. This is most often done via Docker.
+#### Spring Boot
 
-Refer to our [example application](https://github.com/camunda-community-hub/camunda-cloud-examples/tree/main/twitter-review-java-springboot).
+Develop your own process solutions as [Spring Boot](https://spring.io/projects/spring-boot) applications. This involves setting up a new Spring Boot project, either manually or using tools like [Spring Initializr](https://start.spring.io/).
 
-We decided on this stack for the following reasons:
+Integrate [Spring Zeebe](https://github.com/camunda-community-hub/spring-zeebe) into the Spring Boot project by adding necessary dependencies to the project’s pom.xml file and configuring the application to use Camunda services.
 
-- All components are open source and easily available.
-- SaaS is the easiest way to consume capabilities like a workflow engine.
-- Spring Boot is currently the most adopted way of building Java applications.
-- Spring Boot applications are easy to customize as well as easy to roll out into test and production environments, either on-premise or in the cloud.
+#### Maven
 
-Take a look at the [getting started guide for microservices orchestration](/guides/getting-started-orchestrate-microservices.md) or follow the instructions in [Spring Zeebe](https://github.com/camunda-community-hub/spring-zeebe) to get started.
+Use [Maven](https://maven.apache.org/) to manage the build lifecycle of the application.
 
-## Polyglot stacks
+#### IDE selection
 
-You can develop process solutions as described with Java above also in any other programming language. Simply use the [existing language clients / SDKs](../../../apis-tools/working-with-apis-tools.md) for doing this.
+Select an Integrated Development Environment (IDE) that supports Java development, Maven, and Spring Boot. Frequently used options include Visual Studio Code, IntelliJ IDEA, or Eclipse.
 
-<!--
-## The JavaScript greenfield stack
+#### Java runtime
 
-## The C# greenfield stack
--->
+Install and use OpenJDK 17 as your Java runtime environment. Download it from the [official JDK 17 download page](https://jdk.java.net/17/).
 
-## Customize your stack
+#### Modeling
+
+Download and use Camunda Modeler for designing and modeling business processes. Modeler is available [here](https://camunda.org/download/modeler/).
+
+#### Code integration
 
-### Running Camunda 8 self-managed
+Incorporate all Java code and BPMN process models into the Spring Boot project, ensuring that they are structured correctly and referenced properly within the application.
 
-You can also run Camunda 8 self-managed on your own Kubernetes cluster. Details can be found in the [deployment docs](../../../self-managed/platform-deployment/overview.md).
+### Run the process application:
 
-While there [exists a Docker Compose configuration](/docs/self-managed/platform-deployment/docker/) to run Camunda 8 locally, this is not meant to be used for production, but rather to quickly startup components on a developer machine to be able to play around.
+To run the process application, transfer the `jar` to the desired server.
 
-### Modeling for executable processes
+Start the application using the command `java -jar YourProcessApplication.jar`. Frequently, this deployment process is managed through Docker for ease of use.
+
+For a practical implementation, refer to our [example application on GitHub](https://github.com/camunda-community-hub/camunda-cloud-examples/tree/main/twitter-review-java-springboot), which demonstrates a typical setup for a Spring Boot-based process application with Camunda.
+
+<!-- This should be moved from the Community Hub -->
+
+## Customize your stack
 
-We distinguish two different roles modeling in BPM projects:
+### Polyglot stacks
 
-- _Process developers_ develop an executable process implementation. Process developers implementing solutions with Camunda must use Camunda Modeler to model executable processes, edit technical attributes, and manage and version (e.g. in Git or SVN) the resulting (XML) files as part of the development project.
+You can develop process solutions as described with Java above also in any other programming language, including JavaScript. Use the [existing language clients and SDKs](/apis-tools/working-with-apis-tools.md) for doing this.
 
-- _Process analysts_ capture the operational know how about a process. For this part of the work, it is possible to use a different tool than Camunda Modeler.
+### Run Camunda 8 Self-Managed
 
-|                                                               | Camunda Modeler                                                             | Third-Party Modeler (BPMN Standard Compliant)                                                                                                                               | Third-Party Modeler (Non-Compliant to Standard) |
-| ------------------------------------------------------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
-| Roundtrip in between process analysts and developers possible | &#10004;                                                                    | &#10004; (Carefully check level of BPMN compliance - the [Model Interchange Working Group](http://bpmn-miwg.github.io/bpmn-miwg-tools/) can serve as a first starting point |                                                 |
-| Use for process analysts                                      | &#10004;                                                                    | &#10004;                                                                                                                                                                    |                                                 |
-| Use for process developers                                    | &#10004;                                                                    |                                                                                                                                                                             |                                                 |
-| Use when                                                      | You do not have a BPMN standard compliant modeling tool already rolled out. | You already rolled out a BPMN tool with a standard compliancy sufficient for roundtrip.                                                                                     | Try to avoid                                    |
-|                                                               | [Download](https://camunda.org/download/modeler/)                           | [e.g. Cawemo](http://cawemo.com/)                                                                                                                                           |                                                 |
+Run Camunda 8 on your Kubernetes cluster. For local development, a [Docker Compose configuration is available](/self-managed/platform-deployment/docker.md), though not for production use. Learn more in the [deployment docs](/self-managed/platform-deployment/overview.md).

docs/components/best-practices/architecture/sizing-your-environment.md

@@ -93,7 +93,7 @@ Furthermore, data is also sent Operate and Optimize, which store data in Elastic
 Elasticsearch needs enough memory available to load a large amount of this data into memory.
 :::
 
-Assuming a [typical payload of 15 process variables (simple strings, numbers or booleans)](https://github.com/camunda-cloud/zeebe/blob/develop/benchmarks/project/src/main/resources/bpmn/typical_payload.json) we measured the following approximations for disk space requirements using Camunda 8 SaaS 1.2.4. Please note, that these are not exact numbers, but they might give you an idea what to expect:
+Assuming a [typical payload of 15 process variables (simple strings, numbers or booleans)](https://github.com/camunda/zeebe/blob/main/zeebe/benchmarks/project/src/main/resources/bpmn/typical_payload.json) we measured the following approximations for disk space requirements using Camunda 8 SaaS 1.2.4. Please note, that these are not exact numbers, but they might give you an idea what to expect:
 
 - Zeebe: 75 kb / PI
 - Operate: 57 kb / PI

docs/components/best-practices/development/dealing-with-problems-and-exceptions.md

@@ -152,7 +152,7 @@ In BPMN process definitions, we can explicitly model an end event as an error.
 In case the item is not available, we finish the process with an **error end event**.
 
 :::note
-You can mimic a BPMN error in your glue code by using the [`ThrowError`](/apis-tools/zeebe-api/gateway-service.md#throwerror-rpc) API. The consequences for the process are the same as if it were an explicit error end event. So, in case your 'purchase' activity is not a sub process, but a service task, it could throw a BPMN Error informing the process that the good is unavailable.
+You can mimic a BPMN error in your glue code by using the [`ThrowError`](/apis-tools/zeebe-api/gateway-service.md#throwerror-rpc) API. The consequences for the process are the same as if it were an explicit error end event. So, in case your 'purchase' activity is not a subprocess, but a service task, it could throw a BPMN Error informing the process that the good is unavailable.
 :::
 
 Example in Java:

docs/components/best-practices/development/service-integration-patterns.md

@@ -184,13 +184,13 @@ We typically try to avoid the event-based gateway, as it is hard to understand f
 
 As a fourth possibility, you can add event subprocesses, which get activated whenever some event is received while the process is still active in some other area. In the above example, you could model the happy path and model all deviations as event subprocesses.
 
-![Event sub process to capture different response messages](service-integration-patterns-assets/response-event-subprocess.png)
+![Event subprocess to capture different response messages](service-integration-patterns-assets/response-event-subprocess.png)
 
-This pattern is pretty handy, but also needs some explanation to people new to BPMN. It has one downside you need to know: once your process instance moves to the sub process, you can’t easily go back to the typical flow. To some extent this problem can be solved by advanced modeling patterns like shown in the [allow for order cancellation anytime](../../modeling/building-flexibility-into-bpmn-models/#allow-for-order-cancellation-any-time) example.
+This pattern is pretty handy, but also needs some explanation to people new to BPMN. It has one downside you need to know: once your process instance moves to the subprocess, you can’t easily go back to the typical flow. To some extent this problem can be solved by advanced modeling patterns like shown in the [allow for order cancellation anytime](../../modeling/building-flexibility-into-bpmn-models/#allow-for-order-cancellation-any-time) example.
 
 At the same time, the event subprocess has a superpower worth mentioning: you can now wait for cancellation messages in whole chunks of your process — it could arrive anytime.
 
-|                   | Receive task with boundary events                                                                     | Payload and XOR-gateway                                                                   | Event-based gateway                                                                          | Event sub process                                                                      |
+|                   | Receive task with boundary events                                                                     | Payload and XOR-gateway                                                                   | Event-based gateway                                                                          | Event subprocess                                                                       |
 | ----------------- | ----------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
 |                   | ![Boundary Events](service-integration-patterns-assets/response-boundary-message-events.png)          | ![XOR Gateway](service-integration-patterns-assets/response-gateway.png)                  | ![Event-based Gateway](service-integration-patterns-assets/response-event-based-gateway.png) | ![Event Subprocess](service-integration-patterns-assets/response-event-subprocess.png) |
 | Understandability | Easy                                                                                                  | Very easy                                                                                 | Hard                                                                                         | Medium                                                                                 |