Merge branch 'main' into cg-redhat-statement

.github/workflows/publish-prod.yaml

@@ -33,6 +33,8 @@ jobs:
         run: npm run build
         env:
           NODE_OPTIONS: --max_old_space_size=8192
+          DOCS_SITE_URL: https://docs.camunda.io
+          DOCS_SITE_BASE_URL: /
       - name: Get Github Actions IP
         id: ip
         uses: haythem/[email protected]

.github/workflows/publish-stage.yaml

@@ -22,14 +22,14 @@ jobs:
         run: npm ci
       - name: Cache Docusaurus
         uses: ./.github/actions/docusaurus-cache
-      - name: Update URL
-        run: 'sed -i ''s!url: "https://docs.camunda.io"!url: "https://stage.docs.camunda.io"!g'' docusaurus.config.js'
       - name: Update redirects for environment
         run: "sed -i 's!https://unsupported.docs.camunda.io!https://stage.unsupported.docs.camunda.io!g' ./static/.htaccess"
       - name: Build
         run: npm run build
         env:
           NODE_OPTIONS: --max_old_space_size=8192
+          DOCS_SITE_URL: https://stage.docs.camunda.io
+          DOCS_SITE_BASE_URL: /
       - name: Get Github Actions IP
         id: ip
         uses: haythem/[email protected]

docs/components/best-practices/development/understanding-transaction-handling-c7.md

@@ -90,29 +90,29 @@ Aside a general strategy to mark service tasks as being save points you will oft
 
 **Do** configure a savepoint **after**
 
-- _User tasks_ <img src="/img/bpmn-elements/task-user.svg" width="40"/>: This savepoint allows users to complete their tasks without waiting for expensive subsequent steps and without seeing an unexpected rollback of their user transaction to the waitstate before the user task. Sometimes, e.g. when validating user input by means of a subsequent step, you want exactly that: rolling back the user transaction to the user task waitstate. In that case you might want to introduce a savepoint right after the validation step.
+- _User tasks_ <img src="/img/bpmn-elements/task-user.svg"/>: This savepoint allows users to complete their tasks without waiting for expensive subsequent steps and without seeing an unexpected rollback of their user transaction to the waitstate before the user task. Sometimes, e.g. when validating user input by means of a subsequent step, you want exactly that: rolling back the user transaction to the user task waitstate. In that case you might want to introduce a savepoint right after the validation step.
 
-- Service Tasks (or other steps) causing _Non-idempotent Side Effects_ <img src="/img/bpmn-elements/task-service.svg" alt="Service Task" width="40" /> <img src="/img/bpmn-elements/task-script.svg" alt="Script Task" width="40" /> <img src="/img/bpmn-elements/task-send.svg" alt="Send Task" width="40" /> <img src="/img/bpmn-elements/message-intermediate-send.svg" alt="Message Intermediate Event" width="40" /> <img src="/img/bpmn-elements/message-end.svg" alt="Message End Event" width="40" />: This savepoint makes sure that a side effect which must not happen more often than once is not accidentally repeated because any subsequent steps might roll back the transaction to a savepoint well before the affected step. End Events should be included if the process can be called from other processes.
+- Service Tasks (or other steps) causing _Non-idempotent Side Effects_ <img src="/img/bpmn-elements/task-service.svg" alt="Service Task" /> <img src="/img/bpmn-elements/task-script.svg" alt="Script Task" /> <img src="/img/bpmn-elements/task-send.svg" alt="Send Task" /> <img src="/img/bpmn-elements/message-intermediate-send.svg" alt="Message Intermediate Event" /> <img src="/img/bpmn-elements/message-end.svg" alt="Message End Event" />: This savepoint makes sure that a side effect which must not happen more often than once is not accidentally repeated because any subsequent steps might roll back the transaction to a savepoint well before the affected step. End Events should be included if the process can be called from other processes.
 
-- Service tasks (or other steps) executing _expensive Ccmputations_ <img src="/img/bpmn-elements/task-service.svg" alt="Service Task" width="40" /> <img src="/img/bpmn-elements/task-script.svg" alt="Script Task" width="40" /> <img src="/img/bpmn-elements/task-send.svg" alt="Send Task" width="40" /> <img src="/img/bpmn-elements/message-intermediate-send.svg" alt="Message Intermediate Event" width="40" /> <img src="/img/bpmn-elements/message-end.svg" alt="Message End Event" width="40" />: This savepoint makes sure that a computationally expensive step does not have to be repeated just because any subsequent steps might roll back the transaction to a savepoint well before the affected step. End Events should be included if the process can be called from other processes.
+- Service tasks (or other steps) executing _expensive Ccmputations_ <img src="/img/bpmn-elements/task-service.svg" alt="Service Task" /> <img src="/img/bpmn-elements/task-script.svg" alt="Script Task" /> <img src="/img/bpmn-elements/task-send.svg" alt="Send Task" /> <img src="/img/bpmn-elements/message-intermediate-send.svg" alt="Message Intermediate Event" /> <img src="/img/bpmn-elements/message-end.svg" alt="Message End Event" />: This savepoint makes sure that a computationally expensive step does not have to be repeated just because any subsequent steps might roll back the transaction to a savepoint well before the affected step. End Events should be included if the process can be called from other processes.
 
-- Receive tasks (or other steps) catching _external events_, possibly with payload <img src="/img/bpmn-elements/task-receive.svg" alt="Receive Task" width="40" /> <img src="/img/bpmn-elements/message-intermediate.svg" alt="Message Intermediate Event" width="40" /> <img src="/img/bpmn-elements/signal-intermediate.svg" alt="Signal Intermediate Event" width="40" /> : This savepoint makes sure that a external event like a message is persisted as soon as possible. It cannot get lost just because any subsequent steps might roll back the transaction to a savepoint well before the affected step. This applies also to External Service Tasks.
+- Receive tasks (or other steps) catching _external events_, possibly with payload <img src="/img/bpmn-elements/task-receive.svg" alt="Receive Task" /> <img src="/img/bpmn-elements/message-intermediate.svg" alt="Message Intermediate Event" /> <img src="/img/bpmn-elements/signal-intermediate.svg" alt="Signal Intermediate Event" /> : This savepoint makes sure that a external event like a message is persisted as soon as possible. It cannot get lost just because any subsequent steps might roll back the transaction to a savepoint well before the affected step. This applies also to External Service Tasks.
 
 **Do** configure a savepoint **before**
 
-- _Start events_ <img src="/img/bpmn-elements/none-start.svg" alt="None Start Event" width="40" /> <img src="/img/bpmn-elements/message-start.svg" alt="Message Start Event" width="40" /> <img src="/img/bpmn-elements/signal-start.svg" alt="Signal Start Event" width="40" /> <img src="/img/bpmn-elements/timer-start.svg" alt="Timer Start Event" width="40" />: This savepoint allows to immediately return a process instance object to the user thread creating it - well before anything happens in the process instance.
+- _Start events_ <img src="/img/bpmn-elements/none-start.svg" alt="None Start Event" /> <img src="/img/bpmn-elements/message-start.svg" alt="Message Start Event" /> <img src="/img/bpmn-elements/signal-start.svg" alt="Signal Start Event" /> <img src="/img/bpmn-elements/timer-start.svg" alt="Timer Start Event" />: This savepoint allows to immediately return a process instance object to the user thread creating it - well before anything happens in the process instance.
 
-- Service tasks (or other steps) invoking _remote systems_ <img src="/img/bpmn-elements/task-service.svg" alt="Service Task" width="40" /> <img src="/img/bpmn-elements/task-script.svg" alt="Script Task" width="40" /> <img src="/img/bpmn-elements/task-send.svg" alt="Send Task" width="40" /> <img src="/img/bpmn-elements/message-intermediate-send.svg" alt="Message Intermediate Event" width="40" /> <img src="/img/bpmn-elements/message-end.svg" alt="Message End Event" width="40" />: This savepoint makes sure that you always transactionally separate the potentially more often failing remote calls from anything that happens before such a step. If a service call fails you will observe the process instance waiting in the corresponding service task in cockpit.
+- Service tasks (or other steps) invoking _remote systems_ <img src="/img/bpmn-elements/task-service.svg" alt="Service Task" /> <img src="/img/bpmn-elements/task-script.svg" alt="Script Task" /> <img src="/img/bpmn-elements/task-send.svg" alt="Send Task" /> <img src="/img/bpmn-elements/message-intermediate-send.svg" alt="Message Intermediate Event" /> <img src="/img/bpmn-elements/message-end.svg" alt="Message End Event" />: This savepoint makes sure that you always transactionally separate the potentially more often failing remote calls from anything that happens before such a step. If a service call fails you will observe the process instance waiting in the corresponding service task in cockpit.
 
-- _Parallel joins_ <img src="/img/bpmn-elements/gateway-parallel.svg" alt="Parallel Join" width="40" /> <img src="/img/bpmn-elements/gateway-inclusive.svg" alt="Inclusive Join" width="40" /> <img src="/img/bpmn-elements/task-service-multi.svg" alt="Multiinstance Task" width="40" />: Parallel joins synchronize separate process pathes, which is why one of two path executions arriving at a parallel join at the same time will be rolled back with an optimistic locking exception and must be retryed later on. Therefore such a savepoint makes sure that the path synchronisation will be taken care of by Camunda's internal job executor. Note that for multi instance activities, there exists a dedicated "multi instance asynchronous after" flag which saves every single instance of those multiple instances directly after their execution, hence still "before" their technical synchronization.
+- _Parallel joins_ <img src="/img/bpmn-elements/gateway-parallel.svg" alt="Parallel Join" /> <img src="/img/bpmn-elements/gateway-inclusive.svg" alt="Inclusive Join" /> <img src="/img/bpmn-elements/task-service-multi.svg" alt="Multiinstance Task" />: Parallel joins synchronize separate process pathes, which is why one of two path executions arriving at a parallel join at the same time will be rolled back with an optimistic locking exception and must be retryed later on. Therefore such a savepoint makes sure that the path synchronisation will be taken care of by Camunda's internal job executor. Note that for multi instance activities, there exists a dedicated "multi instance asynchronous after" flag which saves every single instance of those multiple instances directly after their execution, hence still "before" their technical synchronization.
 
 The Camunda JobExecutor works (by default) with [exclusive jobs](https://docs.camunda.org/manual/latest/user-guide/process-engine/the-job-executor/#exclusive-jobs), meaning that just one exclusive job per process instance may be executed at once. Hence, job executor threads will by default not cause optimistic locking exceptions at parallel joins "just by themselves", but other threads using the Camunda API might cause them - either for themselves or also for the job executor.
 
 **Don't** configure save points **before**
 
-- User tasks and other _wait states_ <img src="/img/bpmn-elements/task-user.svg" alt="User Task" width="40" /> <img src="/img/bpmn-elements/task-receive.svg" alt="ScrReceiveipt Task" width="40" /> <img src="/img/bpmn-elements/message-intermediate.svg" alt="Message Intermediate Event" width="40" /> <img src="/img/bpmn-elements/signal-intermediate.svg" alt="Signal Intermediate Event" width="40" /> <img src="/img/bpmn-elements/timer-intermediate.svg" alt="Timer Intermediate Event" width="40" /> <img src="/img/bpmn-elements/gateway-event.svg" alt="Event Based Gateway" width="40" /> including steps configured as _external tasks_ <img src="/img/bpmn-elements/task-service.svg" alt="Service Task" width="40" /> <img src="/img/bpmn-elements/task-script.svg" alt="Script Task" width="40" /> <img src="/img/bpmn-elements/task-send.svg" alt="Send Task" width="40" /> <img src="/img/bpmn-elements/message-intermediate-send.svg" alt="Message Intermediate Event" width="40" /> <img src="/img/bpmn-elements/message-end.svg" alt="Message End Event" width="40" />: Such savepoints just introduce overhead as [wait-states](https://docs.camunda.org/manual/latest/user-guide/process-engine/transactions-in-processes/#wait-states) on itself finish the transaction and wait for external intervention anyway.
+- User tasks and other _wait states_ <img src="/img/bpmn-elements/task-user.svg" alt="User Task" /> <img src="/img/bpmn-elements/task-receive.svg" alt="ScrReceiveipt Task" /> <img src="/img/bpmn-elements/message-intermediate.svg" alt="Message Intermediate Event" /> <img src="/img/bpmn-elements/signal-intermediate.svg" alt="Signal Intermediate Event" /> <img src="/img/bpmn-elements/timer-intermediate.svg" alt="Timer Intermediate Event" /> <img src="/img/bpmn-elements/gateway-event.svg" alt="Event Based Gateway" /> including steps configured as _external tasks_ <img src="/img/bpmn-elements/task-service.svg" alt="Service Task" /> <img src="/img/bpmn-elements/task-script.svg" alt="Script Task" /> <img src="/img/bpmn-elements/task-send.svg" alt="Send Task" /> <img src="/img/bpmn-elements/message-intermediate-send.svg" alt="Message Intermediate Event" /> <img src="/img/bpmn-elements/message-end.svg" alt="Message End Event" />: Such savepoints just introduce overhead as [wait-states](https://docs.camunda.org/manual/latest/user-guide/process-engine/transactions-in-processes/#wait-states) on itself finish the transaction and wait for external intervention anyway.
 
-- _All forking_ and _exclusively joining gateways_ <img src="/img/bpmn-elements/gateway-exclusive.svg" alt="Exclusive Gateway" width="40" /> <img src="/img/bpmn-elements/gateway-parallel.svg" alt="Parallel Join" width="40" /> <img src="/img/bpmn-elements/gateway-inclusive.svg" alt="Inclusive Join" width="40" />: There should just be no need to do that, unless execution listeners are configured at such points, which could fail and might need to be transactionally separated from other parts of the execution.
+- _All forking_ and _exclusively joining gateways_ <img src="/img/bpmn-elements/gateway-exclusive.svg" alt="Exclusive Gateway" /> <img src="/img/bpmn-elements/gateway-parallel.svg" alt="Parallel Join" /> <img src="/img/bpmn-elements/gateway-inclusive.svg" alt="Inclusive Join" />: There should just be no need to do that, unless execution listeners are configured at such points, which could fail and might need to be transactionally separated from other parts of the execution.
 
 ### Adding save points automatically to every model
 

docusaurus.config.js

@@ -3,16 +3,18 @@ const { unsupportedVersions } = require("./src/versions");
 
 const latestVersion = require("./src/versions").versionMappings[0].docsVersion;
 
+const docsSiteUrl = process.env.DOCS_SITE_URL || "https://docs.camunda.io";
+
 module.exports = {
   title: "Camunda 8 Docs",
   tagline:
     "Start orchestrating your processes with Camunda 8 SaaS or Self-Managed.",
   // url: "https://camunda-cloud.github.io",
-  url: process.env.DOCS_SITE_URL || "https://docs.camunda.io",
+  url: docsSiteUrl,
   // baseUrl: "/camunda-cloud-documentation/",
   baseUrl: process.env.DOCS_SITE_BASE_URL || "/",
   customFields: {
-    canonicalUrlRoot: "https://docs.camunda.io",
+    canonicalUrlRoot: docsSiteUrl,
   },
   onBrokenLinks: "throw",
   onBrokenMarkdownLinks: "throw",

hacks/isolateVersion/6-updateCIWorkflows.sh

@@ -13,24 +13,29 @@ sed -i '' "/tags:/a\\
       - \"$ARCHIVED_VERSION.[0-9]+\"
 " .github/workflows/publish-prod.yaml
 
-#   c. replace the main docs remote_path with this isolated version's remote_path.
+#   c. add `unsupported.` to docs URLs
+sed -i '' 's/https:\/\/docs.camunda.io/https:\/\/unsupported.docs.camunda.io/' .github/workflows/publish-prod.yaml
+
+#   d. replace the main docs remote_path with this isolated version's remote_path.
 sed -i '' "s/remote_path: \${{ secrets.AWS_PROD_PUBLISH_PATH }}/remote_path: \${{ secrets.AWS_PROD_PUBLISH_PATH_UNSUPPORTED }}\/$ARCHIVED_VERSION/g" .github/workflows/publish-prod.yaml
 
+#   e. update `DOCS_SITE_BASE_URL` to specify isolated version
+sed -i '' "s/DOCS_SITE_BASE_URL: \//DOCS_SITE_BASE_URL: \/$ARCHIVED_VERSION\//" .github/workflows/publish-prod.yaml
+
 # 3. publish-stage:
-sed -i '' '/Disable Indexing/{N; d;}' .github/workflows/publish-stage.yaml
 
 #   a. replace `branches: - main` with `branches: - unsupported/{version}`
 sed -i '' "s/- \"main\"/- \"unsupported\/$ARCHIVED_VERSION\"/" .github/workflows/publish-stage.yaml
 
-#   b. remove `disable indexing` step
-
-#   c. add `unsupported.` to docs URLs
+#   b. add `unsupported.` to docs URLs
 sed -i '' 's/https:\/\/docs.camunda.io/https:\/\/unsupported.docs.camunda.io/' .github/workflows/publish-stage.yaml
 sed -i '' 's/https:\/\/stage.docs.camunda.io/https:\/\/stage.unsupported.docs.camunda.io/' .github/workflows/publish-stage.yaml
 
-#   d. replace `${{ secrets.AWS_STAGE_PUBLISH_PATH }}` with `${{ secrets.AWS_STAGE_PUBLISH_PATH_UNSUPPORTED }}/{version}`
+#   c. replace `${{ secrets.AWS_STAGE_PUBLISH_PATH }}` with `${{ secrets.AWS_STAGE_PUBLISH_PATH_UNSUPPORTED }}/{version}`
 sed -i '' "s/remote_path: \${{ secrets.AWS_STAGE_PUBLISH_PATH }}/remote_path: \${{ secrets.AWS_STAGE_PUBLISH_PATH_UNSUPPORTED }}\/$ARCHIVED_VERSION/g" .github/workflows/publish-stage.yaml
 
+#   d. update `DOCS_SITE_BASE_URL` to specify isolated version
+sed -i '' "s/DOCS_SITE_BASE_URL: \//DOCS_SITE_BASE_URL: \/$ARCHIVED_VERSION\//" .github/workflows/publish-stage.yaml
 
 git add .github/workflows
 git commit -m "archiving($ARCHIVED_VERSION): update CI workflows"

hacks/isolateVersion/7-updateDocusaurusConfig.sh

@@ -3,9 +3,6 @@ notify "Updating docusaurus.config.js..."
 # Update `url` to include `unsupported`
 sed -i '' "s/docs.camunda.io/unsupported.docs.camunda.io/" docusaurus.config.js
 
-# Update `baseUrl` to specify isolated version
-sed -i '' "s/baseUrl: \"\\/\"/baseUrl: \"\/$ARCHIVED_VERSION\/\"/" docusaurus.config.js
-
 # Update footer social icons based on the new baseUrl
 sed -i '' "s/src= \"\/img\//src=\"\/$ARCHIVED_VERSION\/img\//g" docusaurus.config.js