From d4e2177cb19e38a03738b5dd7644cc1a89427e0c Mon Sep 17 00:00:00 2001 From: Rosie Yohannan Date: Wed, 24 Sep 2025 12:45:20 +0100 Subject: [PATCH 1/4] add mermaid antora extension --- antora-playbook.yml | 19 ++++++++++++++++++- .../templates/pages/test-page-one.adoc | 11 +++++++++++ package-lock.json | 7 +++++++ package.json | 1 + ui/src/css/doc.css | 15 +++++++++++++++ 5 files changed, 52 insertions(+), 1 deletion(-) diff --git a/antora-playbook.yml b/antora-playbook.yml index 637fb090f2..7ec480fe35 100644 --- a/antora-playbook.yml +++ b/antora-playbook.yml @@ -67,4 +67,21 @@ urls: html_extension_style: indexify antora: extensions: - - ./extensions/unlisted-pages-extension.js \ No newline at end of file + - ./extensions/unlisted-pages-extension.js + - require: '@sntke/antora-mermaid-extension' + mermaid_library_url: https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs + script_stem: head-scripts + mermaid_initialize_options: + start_on_load: true + theme: base + security_level: loose + theme_variables: + primary_color: '#00DB74' + primary_text_color: '#161616' + primary_border_color: '#00A657' + line_color: '#2152E5' + secondary_color: '#EDEDED' + tertiary_color: '#F7F7F7' + background: '#FFFFFF' + main_bkg: '#EDEDED' + text_color: '#161616' \ No newline at end of file diff --git a/docs/contributors/modules/templates/pages/test-page-one.adoc b/docs/contributors/modules/templates/pages/test-page-one.adoc index 507dac37ca..04bd31ce15 100644 --- a/docs/contributors/modules/templates/pages/test-page-one.adoc +++ b/docs/contributors/modules/templates/pages/test-page-one.adoc @@ -16,6 +16,17 @@ WARNING: *Want to see a warning?* This is a warning. CAUTION: *Want to see a caution?* This is a caution. +== Diagram + +[mermaid] +.... +sequenceDiagram + participant Alice + participant Bob + Alice->>Bob: Hello Bob, how are you? + Bob-->>Alice: Great! +.... + Sometimes we have sections separated by horizontal lines, like this: --- diff --git a/package-lock.json b/package-lock.json index f15342d466..c8a11c779a 100644 --- a/package-lock.json +++ b/package-lock.json @@ -18,6 +18,7 @@ "@antora/site-generator": "3.1.12", "@dotenvx/dotenvx": "^1.40.0", "@redocly/cli": "^2.0.0", + "@sntke/antora-mermaid-extension": "^0.0.8", "browser-sync": "^3.0.4", "gulp": "^5.0.0", "snippet-enricher-cli": "0.0.8" @@ -1528,6 +1529,12 @@ "integrity": "sha512-+Fj43pSMwJs4KRrH/938Uf+uAELIgVBmQzg/q1YG10djyfA3TnrU8N8XzqCh/okZdszqBQTZf96idMfE5lnwTA==", "dev": true }, + "node_modules/@sntke/antora-mermaid-extension": { + "version": "0.0.8", + "resolved": "https://registry.npmjs.org/@sntke/antora-mermaid-extension/-/antora-mermaid-extension-0.0.8.tgz", + "integrity": "sha512-tTGNECQJcJaz2m/W2izgVNLO78LBq1OyNxIpTYU/IslkRjN62ghZfK25sZTfpvJQjKeNTOnx+SmFcCpq/Sn3FQ==", + "dev": true + }, "node_modules/@socket.io/component-emitter": { "version": "3.1.2", "resolved": "https://registry.npmjs.org/@socket.io/component-emitter/-/component-emitter-3.1.2.tgz", diff --git a/package.json b/package.json index 0f4d87a323..fcb8be9986 100644 --- a/package.json +++ b/package.json @@ -22,6 +22,7 @@ "@antora/site-generator": "3.1.12", "@dotenvx/dotenvx": "^1.40.0", "@redocly/cli": "^2.0.0", + "@sntke/antora-mermaid-extension": "^0.0.8", "browser-sync": "^3.0.4", "gulp": "^5.0.0", "snippet-enricher-cli": "0.0.8" diff --git a/ui/src/css/doc.css b/ui/src/css/doc.css index f66a786fc5..bf76f1b801 100644 --- a/ui/src/css/doc.css +++ b/ui/src/css/doc.css @@ -1439,4 +1439,19 @@ .doc .circle-red { color: #8F001C !important; font-weight: var(--heading-font-weight); +} + +/* === MERMAID DIAGRAM STYLES === */ + +/* Basic container styling */ +.doc .mermaid { + text-align: center; + margin: 1rem 0; + overflow-x: auto; +} + +/* Responsive sizing */ +.doc .mermaid svg { + max-width: 100%; + height: auto; } \ No newline at end of file From a2c26a4230c0ef2165fb64009dc3f85e334897c2 Mon Sep 17 00:00:00 2001 From: Rosie Yohannan Date: Wed, 24 Sep 2025 22:49:47 +0100 Subject: [PATCH 2/4] add pipeline state diagram --- .../modules/orchestrate/pages/pipelines.adoc | 25 +++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/docs/guides/modules/orchestrate/pages/pipelines.adoc b/docs/guides/modules/orchestrate/pages/pipelines.adoc index beddb75409..156422a38a 100644 --- a/docs/guides/modules/orchestrate/pages/pipelines.adoc +++ b/docs/guides/modules/orchestrate/pages/pipelines.adoc @@ -114,6 +114,31 @@ Once you have set up a pipeline you need to set up a trigger to connect it to. S -- ==== +== Pipeline states + +[mermaid] +---- +--- +title: Pipeline States +--- +stateDiagram-v2 + state "setup-pending" as setuppending + + state type <> + + [*] --> type + type --> setuppending : Dynamic config enabled and setup true in config + type --> pending : Dynamic config not enabled, or setup true not in config + + setuppending --> setup + setup --> pending + pending --> created + pending --> errored + created --> [*] + errored --> [*] + +---- + == Pipeline parameters Pipeline parameters are declared using the `parameters` key at the top level of a `.circleci/config.yml` file. Pipeline parameters can be referenced by value and used as a configuration variable under the scope `pipeline.parameters`. From 9516cd2ef7b0da7c777c43dc7439b99ec3edf8d8 Mon Sep 17 00:00:00 2001 From: Rosie Yohannan Date: Thu, 25 Sep 2025 15:48:02 +0100 Subject: [PATCH 3/4] add state diagrams and try to avoid cursor from changing to zoom --- .../modules/orchestrate/pages/jobs-steps.adoc | 38 +++++++++++++++ .../modules/orchestrate/pages/pipelines.adoc | 8 ++-- .../modules/orchestrate/pages/workflows.adoc | 46 ++++++++++++++++++- ui/src/css/doc.css | 17 +++++++ 4 files changed, 103 insertions(+), 6 deletions(-) diff --git a/docs/guides/modules/orchestrate/pages/jobs-steps.adoc b/docs/guides/modules/orchestrate/pages/jobs-steps.adoc index 98d127d53c..b52850e722 100644 --- a/docs/guides/modules/orchestrate/pages/jobs-steps.adoc +++ b/docs/guides/modules/orchestrate/pages/jobs-steps.adoc @@ -71,6 +71,44 @@ You can set the type of a job by adding the `type` key to the job configuration. See the xref:reference:ROOT:configuration-reference.adoc#job-type[Confirguration reference] page for more information on how to use the different job types. +=== Job status transitions + +.Job status transitions +[mermaid] +---- +stateDiagram-v2 + [*] --> blocked + + blocked --> pending + blocked --> unauthorized : trying to use a context without permission + + pending --> running: For build jobs, Mongo builds are created here + + pending --> skipped : PRs only / ci-skip / no project found / abusive / sanctioned / etc. + pending --> blocked : retriable error + pending --> terminated + + running --> canceled + pending --> canceled + blocked --> canceled + + + running --> failed + running --> success + running --> terminated + + state "terminated-unknown" as terminated + + skipped --> [*] + terminated --> [*] + success --> [*] + failed --> [*] + canceled --> [*] + unauthorized --> [*] + +---- + + [#steps-overview] == Steps overview diff --git a/docs/guides/modules/orchestrate/pages/pipelines.adoc b/docs/guides/modules/orchestrate/pages/pipelines.adoc index 156422a38a..9c732ab403 100644 --- a/docs/guides/modules/orchestrate/pages/pipelines.adoc +++ b/docs/guides/modules/orchestrate/pages/pipelines.adoc @@ -116,19 +116,17 @@ Once you have set up a pipeline you need to set up a trigger to connect it to. S == Pipeline states +.Pipeline states [mermaid] ---- ---- -title: Pipeline States ---- stateDiagram-v2 state "setup-pending" as setuppending state type <> [*] --> type - type --> setuppending : Dynamic config enabled and setup true in config - type --> pending : Dynamic config not enabled, or setup true not in config + type --> setuppending : Dynamic config enabled
and setup true in config + type --> pending : Dynamic config not enabled,
or setup true not in config setuppending --> setup setup --> pending diff --git a/docs/guides/modules/orchestrate/pages/workflows.adoc b/docs/guides/modules/orchestrate/pages/workflows.adoc index b4628f433e..648ff3cd64 100644 --- a/docs/guides/modules/orchestrate/pages/workflows.adoc +++ b/docs/guides/modules/orchestrate/pages/workflows.adoc @@ -823,7 +823,7 @@ image::guides:ROOT:orchestrate-and-trigger/rerun-from-failed-workflows-page.png[ NOTE: If you rerun a workflow containing a job that was previously re-run with SSH, the new workflow runs with SSH enabled for that job, even after SSH capability is disabled at the project level. [#states] -=== Workflow states +== Workflow states Workflows may have one of the following states: @@ -866,10 +866,54 @@ Workflows may have one of the following states: | UNAUTHORIZED | One or more of the jobs terminated with a `unauthorized` job status. The user who triggered the pipeline or approved an approval job does not have access to a required restricted context. | Yes + +| QUEUED +| The workflow is queued due to being part of a serial group. For more informaiton, see the xref:controlling-serial-execution-across-your-organization.adoc[Controlling serial execution across your organization] page. +| No + |=== NOTE: After 90 days non-terminal workflows are automatically by CircleCI. +The following state diagram shows the possible states and transitions of a workflow: + +.Workflow states +[mermaid] +---- +stateDiagram-v2 + [*] --> running + + running --> success + + running --> failing + + running --> on_hold + on_hold --> canceled + on_hold --> running : approve job + on_hold --> success + + running --> canceled + failing --> failed + failing --> canceled + + running --> failed + running --> error + running --> not_run + running --> unauthorized + + running --> queued + queued --> running: acquired lock + + success --> [*] + canceled --> [*] + failed --> [*] + error --> [*] + unauthorized --> [*] + not_run --> [*] + +---- + + [#troubleshooting] == Troubleshooting diff --git a/ui/src/css/doc.css b/ui/src/css/doc.css index bf76f1b801..62f09b74fa 100644 --- a/ui/src/css/doc.css +++ b/ui/src/css/doc.css @@ -1454,4 +1454,21 @@ .doc .mermaid svg { max-width: 100%; height: auto; + cursor: default; /* Prevent zoom cursor on hover */ +} + +/* Prevent zoom cursor on mermaid diagrams */ +.doc .mermaid, +.doc .mermaid *, +.doc .imageblock .mermaid, +.doc .imageblock .mermaid *, +.doc .imageblock .content .mermaid, +.doc .imageblock .content .mermaid * { + cursor: default !important; +} + +/* Specifically override the imageblock content zoom cursor when it contains mermaid */ +.doc .imageblock .content .mermaid ~ *, +.doc .imageblock .content .mermaid + * { + cursor: default !important; } \ No newline at end of file From 4ee7f9a521f135bbf051627b9b541476af95da8f Mon Sep 17 00:00:00 2001 From: Rosie Yohannan Date: Wed, 1 Oct 2025 22:28:14 +0100 Subject: [PATCH 4/4] add job state table and fix up diagram --- .../modules/orchestrate/pages/jobs-steps.adoc | 45 ++++++++++++++----- 1 file changed, 33 insertions(+), 12 deletions(-) diff --git a/docs/guides/modules/orchestrate/pages/jobs-steps.adoc b/docs/guides/modules/orchestrate/pages/jobs-steps.adoc index b52850e722..3329895892 100644 --- a/docs/guides/modules/orchestrate/pages/jobs-steps.adoc +++ b/docs/guides/modules/orchestrate/pages/jobs-steps.adoc @@ -69,38 +69,38 @@ There are four types of jobs: You can set the type of a job by adding the `type` key to the job configuration. -See the xref:reference:ROOT:configuration-reference.adoc#job-type[Confirguration reference] page for more information on how to use the different job types. +See the xref:reference:ROOT:configuration-reference.adoc#job-type[Configuration reference] page for more information on how to use the different job types. === Job status transitions +The following diagram and table shows the possible job statuses and transitions. + .Job status transitions [mermaid] ---- stateDiagram-v2 + direction TB [*] --> blocked - blocked --> pending - blocked --> unauthorized : trying to use a context without permission + state "blocked or not run" as pending + blocked --> pending : Job instructed to start but not yet started + blocked --> unauthorized : Trying to use a context without permission + blocked --> canceled - pending --> running: For build jobs, Mongo builds are created here + pending --> running - pending --> skipped : PRs only / ci-skip / no project found / abusive / sanctioned / etc. - pending --> blocked : retriable error - pending --> terminated + pending --> skipped : Only build PRs setting enabled
ci-skip
No project found
Abusive
Sanctioned + pending --> blocked : Rerun running --> canceled pending --> canceled - blocked --> canceled + running --> failed running --> success - running --> terminated - - state "terminated-unknown" as terminated skipped --> [*] - terminated --> [*] success --> [*] failed --> [*] canceled --> [*] @@ -108,6 +108,27 @@ stateDiagram-v2 ---- +[cols="1,2", options="header"] +|=== +| Status | Description + +|Blocked/Not Running | All jobs start off in a blocked state. Jobs called `build` move on to a Not Running state before starting. + +|Running | Job is running. + +| On Hold | The job is running but requires manual approval. + +| Not Run | The job is skipped. + +| Success | The job succeeded. + +| Failed | The job failed or terminated for unknown reasons. + +| Canceled | The job was canceled. An actor might cancel a job, or cancel a workflow. A job may be cancelled due to auto-cancellation. Support engineers can force cancellation of a job. + +| Unauthorized | The job uses a restricted context and the actor that triggered the work does NOT have access to that context. + +|=== [#steps-overview] == Steps overview