Merge branch 'main' into ripCloud

.github/pull_request_template.md

@@ -1,24 +1,35 @@
 ## Description
 
-<!-- This helps the reviewers by providing an overview of what to expect in the PR. Linking to an issue is preferred but not required. -->
-<!-- Add an assignee and use component: labels for good hygiene! -->
+<!-- Provide an overview of what to expect in the PR. -->
+<!-- Link to an associated epic when applicable. -->
+<!-- Add an assignee and use `component:` or version labels for good hygiene! -->
 
 ## When should this change go live?
 
 <!-- PRs merged go to stage.docs.camunda.io first and must be manually released to docs.camunda.io. -->
-<!-- Help the DevEx team prioritize our work (reviews, merges, etc.) by opening PRs sooner. -->
 
-- [ ] This change is not yet live and should not be merged until {ADD_DATE} (apply `hold` label or convert to draft PR)?
-- [ ] There is no urgency with this change.
-- [ ] This change or page is part of a marketing blog, conference talk, or something else on a schedule.
-- [ ] This functionality is already available but undocumented.
-- [ ] This is a bug fix or security concern.
+- [ ] This is a bug fix, security concern, or something that needs **urgent release support**.
+- [ ] This is already available but undocumented and should be released within a week.
+- [ ] This on a **specific schedule** and the assignee will coordinate a release with the DevEx team. (apply `hold` label or convert to draft PR)
+- [ ] This is part of a scheduled alpha or minor. (apply alpha or minor label)
+- [ ] There is **no urgency** with this change and can be released at any time.
 
 ## PR Checklist
 
-<!-- Keep in mind, Camunda maintains 18 months of versions. Backporting your change or including it in multiple versions is common. -->
+<!-- Camunda maintains 18 months of versions. Backporting your change to multiple versions is common. -->
 
-- [ ] I have added changes to the relevant `/versioned_docs` directory, or they are not for an **already released version**.
-- [ ] I have added changes to the main `/docs` directory (aka `/next/`), or they are not for **future versions**.
-- [ ] My changes require an [Engineering review](https://github.com/camunda/camunda-docs/blob/main/howtos/documentation-guidelines.md#review-process), and I've assigned an engineering manager or tech lead as a reviewer, or my changes do not require an Engineering review.
-- [ ] My changes require a [technical writer review](https://github.com/camunda/camunda-docs/blob/main/howtos/documentation-guidelines.md#review-process), and I've assigned @christinaausley as a reviewer, or my changes do not require a technical writer review.
+- [ ] My changes are for an **already released minor** and are in `/versioned_docs` directory.
+- [ ] My changes are for the **next minor** and are in `/docs` directory (aka `/next/`).
+
+<!-- UNCOMMENT THIS SECTION IF APPLICABLE. Adding or removing pages requires extra steps.
+- [ ] I included my new page in the sidebar file(s).
+- [ ] I added a redirect for a renamed or deleted page to the .htaccess file.
+-->
+
+<!-- All changes require either an Engineering review or technical writer review. **Many require both!** -->
+
+- [ ] My changes require an [Engineering review](https://github.com/camunda/camunda-docs/blob/main/howtos/documentation-guidelines.md#review-process), and I've assigned the Engineering DRI or delegate.
+- [ ] My changes require a [technical writer review](https://github.com/camunda/camunda-docs/blob/main/howtos/documentation-guidelines.md#review-process), and I've assigned @camunda/tech-writers as a reviewer.
+
+<!-- UNCOMMENT THIS SECTION IF APPLICABLE. Changes to **docs infra**, including updates to workflows and adding new npm packages, must be first discussed via issue or #ask-c8-documentation and linked for context.
+- [ ] My changes require a [docs infrastructure review](https://github.com/camunda/camunda-docs/blob/main/howtos/documentation-guidelines.md#review-process). -->

.github/workflows/add-to-project.yaml

@@ -8,7 +8,7 @@ on:
 
 jobs:
   sync-board:
-    if: github.event.requested_reviewer.login == 'akeller' || github.event.requested_reviewer.login == 'christinaausley'
+    if: github.event.requested_reviewer.login == 'akeller' || github.event.requested_reviewer.login == 'christinaausley' || github.event.requested_reviewer.login == 'conceptualshark' || github.event.requested_team.name == 'Tech Writers'
     runs-on: ubuntu-latest
     steps:
       - name: Get project IDs for later steps

.github/workflows/build-docs.yaml

@@ -27,7 +27,7 @@ jobs:
       - name: Build
         run: npm run build
         env:
-          NODE_OPTIONS: --max_old_space_size=4096
+          NODE_OPTIONS: --max_old_space_size=8192
       - name: Remove https redirect
         run: |
           sed -i '/SERVER_PORT/d;/SERVER_NAME/d' build/.htaccess

.github/workflows/check-versions/version-config.json

@@ -2,21 +2,21 @@
   {
     "version": "next",
     "source": "docs/",
-    "suggestions": ["versioned_docs/version-8.4/"]
+    "suggestions": ["versioned_docs/version-8.5/"]
   },
   {
     "version": "current (main docs)",
-    "source": "versioned_docs/version-8.4/",
+    "source": "versioned_docs/version-8.5/",
     "suggestions": ["docs/"]
   },
   {
     "version": "next",
     "source": "optimize/",
-    "suggestions": ["optimize_versioned_docs/version-3.12.0/"]
+    "suggestions": ["optimize_versioned_docs/version-3.13.0/"]
   },
   {
     "version": "current",
-    "source": "optimize_versioned_docs/version-3.12.0/",
+    "source": "optimize_versioned_docs/version-3.13.0/",
     "suggestions": ["optimize/"]
   }
 ]

.github/workflows/links.yml

@@ -0,0 +1,39 @@
+name: Check external links
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "0 3 1 * *"
+
+jobs:
+  lint:
+    name: links-check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4
+
+      - name: Get Current Timestamp
+        id: timestamp
+        run: echo "TIMESTAMP=$(date +%s)" >> "$GITHUB_ENV"
+
+      - name: Restore lychee cache
+        uses: actions/cache@v3
+        with:
+          path: .lycheecache
+          key: "cache-lychee-${{ env.TIMESTAMP }}"
+          restore-keys: cache-lychee-
+
+      - name: Link Checker
+        uses: lycheeverse/[email protected]
+        with:
+          fail: true
+          args: -c ./lychee-external-links.toml --base . --cache --max-cache-age 1d . --verbose --no-progress 'docs/**/*.md' 'versioned_docs/**/*.md'
+          token: "${{ secrets.GITHUB_TOKEN }}"
+
+      - name: Create Issue From File
+        if: ${{ github.event_name == 'schedule' && env.lychee_exit_code != 0 }}
+        uses: peter-evans/create-issue-from-file@v4
+        with:
+          title: Link Checker Report
+          content-filepath: ./lychee/out.md
+          labels: report, automated issue

.github/workflows/publish-prod.yaml

@@ -11,6 +11,7 @@ on:
       - "!1.2.[0-9]+"
       - "!1.3.[0-9]+"
       - "!8.0.[0-9]+"
+      - "!8.1.[0-9]+"
 
 permissions:
   id-token: write
@@ -30,7 +31,7 @@ jobs:
       - name: Build
         run: npm run build
         env:
-          NODE_OPTIONS: --max_old_space_size=4096
+          NODE_OPTIONS: --max_old_space_size=8192
       - name: Get Github Actions IP
         id: ip
         uses: haythem/[email protected]

.github/workflows/publish-stage.yaml

@@ -27,7 +27,7 @@ jobs:
       - name: Build
         run: npm run build
         env:
-          NODE_OPTIONS: --max_old_space_size=4096
+          NODE_OPTIONS: --max_old_space_size=8192
       - name: Get Github Actions IP
         id: ip
         uses: haythem/[email protected]

CONTRIBUTING.MD

@@ -134,7 +134,7 @@ the Apache Spark contributor guidelines, and the Kubernetes contributor guide.
 [git]: https://git-scm.com/
 [github]: https://skills.github.com/
 [contributor license agreement]: https://cla-assistant.io/camunda-cloud/camunda-cloud-documentation
-[code style guidelines]: https://github.com/camunda/zeebe/wiki/Code-Style
+[code style guidelines]: https://github.com/camunda/camunda/wiki/Code-Style
 [testing best practices]: https://docs.camunda.io/docs/apis-tools/java-client/zeebe-process-test/
 [technical writing style guide]: ./howtos/technical-writing-styleguide.md
-[pull requests and code review]: https://github.com/camunda/zeebe/wiki/Pull-Requests-and-Code-Reviews
+[pull requests and code review]: https://github.com/camunda/camunda/wiki/Pull-Requests-and-Code-Reviews

Dockerfile.build

@@ -11,7 +11,7 @@ RUN npm install
 # Build
 FROM build-setup AS build
 COPY . .
-ENV NODE_OPTIONS="--max_old_space_size=4096"
+ENV NODE_OPTIONS="--max_old_space_size=8192"
 RUN npm run build
 
 # Copy to output directory (so host can access it)

api/generate-api-docs.js

@@ -0,0 +1,58 @@
+const { execSync } = require("child_process");
+
+// More strategies to come, for other APIs.
+const operate = require("./operate/generation-strategy");
+const zeebe = require("./zeebe/generation-strategy");
+const tasklist = require("./tasklist/generation-strategy");
+const apiStrategies = {
+  operate,
+  zeebe,
+  tasklist,
+};
+
+// Execute a command as if we were in the terminal
+function runCommand(command) {
+  const result = execSync(command, { stdio: "inherit" });
+  return result;
+}
+
+// API name must be passed in as an arg.
+const api = process.argv[2];
+if (api === undefined) {
+  const validAPIs = string.join(apiStrategies.join, ", ");
+  console.log(`Please specify an API name. Valid names: ${validAPIs}`);
+  process.exit();
+}
+
+// The API name must be recognized.
+const strategy = apiStrategies[api];
+if (strategy === undefined) {
+  const validAPIs = string.join(apiStrategies.join, ", ");
+  console.error(`Invalid API name ${api}. Valid names: ${validAPIs}`);
+  process.exit();
+}
+
+// All APIs will execute these same steps, with custom-per-API steps
+//   implemented by each API's generation-strategy.js.
+const steps = [
+  // Remove old docs
+  () => runCommand(`docusaurus clean-api-docs ${api} -p api-${api}-openapi`),
+
+  // Run any custom steps before generation
+  strategy.preGenerateDocs,
+
+  // Generate the docs
+  () => runCommand(`docusaurus gen-api-docs ${api} -p api-${api}-openapi`),
+
+  // Run any custom steps after generation
+  strategy.postGenerateDocs,
+
+  // Run prettier against the generated docs. Twice. Yes, twice.
+  //   I don't know why, but the first run always leaves an extra blank line,
+  //   which the second execution removes.
+  () => runCommand(`prettier --write ${strategy.outputDir}`),
+  () => runCommand(`prettier --write ${strategy.outputDir}`),
+];
+
+// Run the steps!
+steps.forEach((step) => step());

api/make-server-dynamic.js

@@ -0,0 +1,27 @@
+const replace = require("replace-in-file");
+
+function makeServerDynamic(specFile) {
+  // The source spec has a hardcoded generated server URL.
+  //   We can make it dynamic so that the user can edit it and get more accurate code samples.
+  console.log("making server dynamic....");
+
+  // Note that `v1` is included in this path.
+  const dynamicServerDefinition = `  - url: "{schema}://{host}:{port}"
+    variables:
+      host:
+        default: localhost
+        description: The hostname of the API server.
+      port:
+        default: "8080"
+        description: The port of the API server.
+      schema:
+        default: http
+        description: The schema of the API server.`;
+  replace.sync({
+    files: specFile,
+    // This regex includes the following `description` line, which becomes inaccurate when we make the server dynamic.
+    from: /^. - url:.*\n.   description:.*$/m,
+    to: dynamicServerDefinition,
+  });
+}
+exports.makeServerDynamic = makeServerDynamic;