Replace PlantUML documentation diagrams with Mermaid

[arturcic]

Summary

• replace PlantUML sequence-diagram generation with Mermaid
• store Mermaid sources and deterministic SVG assets in the repository
• replace the remote PlantUML architecture image with a local generated SVG
• add pinned regeneration and drift-check tooling under docs
• verify Mermaid sources and rendered assets in the documentation workflow

Motivation

The documentation should not depend on a remote diagram-rendering service, and diagram updates should be reproducible and reviewable from source. Keeping Mermaid sources and generated SVGs together also lets CI detect stale documentation assets.

Verification

• npm run diagrams:check
  • 44 documentation scenario tests passed
  • 11 test-generated Mermaid sources verified
  • 12 Mermaid SVGs verified
• focused sequence-diagram and documentation scenario tests passed
• dotnet run/docs.dll --target=BuildDocs
• focused Markdown lint and git diff --check

Closes #5108

[Copilot]

Pull request overview

This pull request migrates GitVersion’s documentation diagrams from PlantUML (including a remotely-rendered diagram) to a repository-local Mermaid workflow, making diagram sources and rendered SVGs reproducible and CI-verifiable.

Changes:

• Switched test-generated sequence-diagram output from PlantUML to Mermaid, including updated fixtures and new unit tests.
• Added pinned Mermaid CLI tooling plus scripts to generate and drift-check Mermaid sources and SVG assets.
• Updated documentation pages to reference local Mermaid-rendered SVGs and Mermaid sources instead of remote PlantUML links.

Reviewed changes

Copilot reviewed 30 out of 54 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/GitVersion.Testing/Helpers/ParticipantSanitizer.cs	Updates sanitizer documentation to Mermaid context.
src/GitVersion.Testing/Fixtures/SequenceDiagram.cs	Reimplements sequence-diagram generation for Mermaid syntax/output.
src/GitVersion.Testing/Fixtures/RepositoryFixtureBase.cs	Aligns fixture diagram events with new Mermaid sequence diagram API (destroy/commit).
src/GitVersion.Core.Tests/IntegrationTests/DocumentationSamplesForGitHubFlow.cs	Writes Mermaid sources for GitHubFlow documentation scenarios.
src/GitVersion.Core.Tests/IntegrationTests/DocumentationSamplesForGitFlow.cs	Writes Mermaid sources for GitFlow documentation scenarios.
src/GitVersion.Core.Tests/IntegrationTests/DocumentationSamples.cs	Updates legacy sample tests to new Destroy(branch, from) signature.
src/GitVersion.Core.Tests/IntegrationTests/DocumentationDiagramWriter.cs	New helper to persist .mmd sources from documentation scenario tests.
src/GitVersion.Core.Tests/IntegrationTests/DevelopScenarios.cs	Updates destroy calls to include source participant.
src/GitVersion.Core.Tests/Fixtures/SequenceDiagramTests.cs	Adds unit tests validating Mermaid output formatting and escaping.
package.json	Adds pinned Mermaid CLI dependency and scripts to generate/check diagrams.
docs/scripts/render-mermaid.mjs	New renderer to generate/check deterministic Mermaid SVGs via mmdc.
docs/scripts/generate-mermaid-sources.mjs	New generator/checker to produce .mmd sources by running documentation scenario tests.
docs/mermaid-config.json	Mermaid configuration enabling deterministic IDs and consistent rendering.
docs/input/docs/learn/how-it-works.md	Replaces remote PlantUML image with local SVG and links to Mermaid source.
docs/input/docs/learn/branching-strategies/githubflow/examples.md	Switches examples to .svg and documents the new regen workflow.
docs/input/docs/learn/branching-strategies/gitflow/examples.md	Switches examples to .svg and documents the new regen workflow.
docs/input/docs/learn/branching-strategies/contribute-examples.md	Updates contributor guidance from PlantUML to Mermaid + new commands.
docs/input/docs/img/version-calculation.svg	Adds locally-rendered Mermaid SVG asset for version calculation diagram.
docs/input/docs/img/DocumentationSamplesForGitHubFlow_ReleaseBranch.svg	Adds locally-rendered Mermaid SVG for GitHubFlow release example.
docs/input/docs/img/DocumentationSamplesForGitHubFlow_FeatureBranch.svg	Adds locally-rendered Mermaid SVG for GitHubFlow feature example.
docs/input/docs/img/DocumentationSamplesForGitFlow_ReleaseBranch.svg	Adds locally-rendered Mermaid SVG for GitFlow release example.
docs/diagrams/version-calculation.mmd	Adds Mermaid source for version calculation diagram.
docs/diagrams/DocumentationSamplesForGitHubFlow_VersionedReleaseBranch.mmd	Adds Mermaid source generated from GitHubFlow scenario test.
docs/diagrams/DocumentationSamplesForGitHubFlow_ReleaseBranch.mmd	Adds Mermaid source generated from GitHubFlow scenario test.
docs/diagrams/DocumentationSamplesForGitHubFlow_FeatureBranch.mmd	Adds Mermaid source generated from GitHubFlow scenario test.
docs/diagrams/DocumentationSamplesForGitFlow_VersionedReleaseBranch.mmd	Adds Mermaid source generated from GitFlow scenario test.
docs/diagrams/DocumentationSamplesForGitFlow_VersionedHotfixBranch.mmd	Adds Mermaid source generated from GitFlow scenario test.
docs/diagrams/DocumentationSamplesForGitFlow_SupportBranch.mmd	Adds Mermaid source generated from GitFlow scenario test.
docs/diagrams/DocumentationSamplesForGitFlow_ReleaseBranch.mmd	Adds Mermaid source generated from GitFlow scenario test.
docs/diagrams/DocumentationSamplesForGitFlow_HotfixBranch.mmd	Adds Mermaid source generated from GitFlow scenario test.
docs/diagrams/DocumentationSamplesForGitFlow_FeatureFromMainBranch.mmd	Adds Mermaid source generated from GitFlow scenario test.
docs/diagrams/DocumentationSamplesForGitFlow_FeatureFromDevelopBranch.mmd	Adds Mermaid source generated from GitFlow scenario test.
docs/diagrams/DocumentationSamplesForGitFlow_DevelopBranch.mmd	Adds Mermaid source generated from GitFlow scenario test.
.github/workflows/docs.yml	Adds npm ci + Mermaid drift verification to the docs workflow.

[Copilot]

Pull request overview

Copilot reviewed 31 out of 55 changed files in this pull request and generated no new comments.

Suppressed comments (1)

docs/scripts/generate-mermaid-sources.mjs:27

• generate-mermaid-sources.mjs hard-codes platform-specific absolute paths to the dotnet host. This will fail for contributors and self-hosted runners where .NET is installed in a different location (even though dotnet is typically available on PATH and via DOTNET_ROOT). Prefer resolving via env vars and/or falling back to dotnet so the docs tooling is portable.

[Copilot]

Pull request overview

Copilot reviewed 31 out of 55 changed files in this pull request and generated no new comments.

Suppressed comments (1)

docs/scripts/generate-mermaid-sources.mjs:27

• The script hard-codes platform-specific absolute paths to the dotnet host and fails if the SDK is installed elsewhere (e.g., macOS ARM Homebrew uses /opt/homebrew/..., custom DOTNET_ROOT, or any PATH-only install). This makes npm run diagrams:sources unnecessarily brittle for contributors and nonstandard CI runners.

[Copilot]

Pull request overview

Copilot reviewed 31 out of 55 changed files in this pull request and generated no new comments.

Suppressed comments (2)

docs/scripts/render-mermaid.mjs:77

• When spawnSync fails to launch the Mermaid CLI (e.g., missing node_modules or wrong platform binary), result.status is typically null and result.error contains the real cause (ENOENT, EACCES, etc.). The current check treats this as a generic non-zero exit and throws an error that hides the underlying problem, making contributor troubleshooting harder.

Consider explicitly handling result.error before checking status, and include the executable path in the message.
docs/scripts/generate-mermaid-sources.mjs:62

• Similar to render-mermaid.mjs, if spawnSync cannot start dotnet (bad DOTNET_ROOT, missing PATH entry), the real failure details are in result.error while result.status is usually null. The current code throws a generic exit-code error, which can obscure the root cause.

Handle result.error explicitly and include the resolved executable path to make failures actionable.

[Copilot]

Pull request overview

Copilot reviewed 31 out of 71 changed files in this pull request and generated no new comments.

Suppressed comments (4)

src/GitVersion.Testing/Fixtures/RepositoryFixtureBase.cs:76

• Remove now writes the diagram "destroy/delete" event before actually removing the branch from the repository. If Repository.Branches.Remove(branch) throws (e.g., missing branch), the generated diagram will incorrectly record a deletion that never happened. Capture the source branch name first, remove the branch, then append the diagram destruction.
  src/GitVersion.Core.Tests/IntegrationTests/DocumentationDiagramWriter.cs:17
• The .mmd output written here depends on Environment.NewLine used by StringBuilder.AppendLine, which can differ across platforms. Because the drift-check compares files byte-for-byte, this can cause false failures or noisy diffs when regenerating on different OSes. Normalize line endings before writing so the committed Mermaid sources remain deterministic.
  docs/scripts/generate-mermaid-sources.mjs:81
• The --check path compares generated .mmd files byte-for-byte (Buffer.equals). That is brittle: line endings (LF vs CRLF) and other benign encoding differences can trigger false "stale" failures. Read the files as UTF-8 text and normalize line endings before comparing so drift checks stay stable across environments.
  docs/scripts/render-mermaid.mjs:41
• --check currently creates docs/input/docs/img/ even when the command is only verifying drift. This introduces an avoidable working-tree side effect (and can leave an empty directory behind in fresh clones). Consider only creating the output directory when generating, not when checking.

[Copilot]

Pull request overview

Copilot reviewed 31 out of 71 changed files in this pull request and generated no new comments.

Suppressed comments (1)

src/GitVersion.Core.Tests/IntegrationTests/DocumentationDiagramWriter.cs:16

• DocumentationDiagramWriter writes the diagram text with platform-specific line endings (from StringBuilder.AppendLine). Because the repo enforces LF checkouts via .gitattributes (* text=auto eol=lf), generating/checking Mermaid sources on Windows will produce CRLF output and make npm run diagrams:sources:check report stale .mmd files. Normalize to \n before writing so the generated sources are OS-independent.

[Copilot]

Pull request overview

Copilot reviewed 31 out of 71 changed files in this pull request and generated no new comments.

Suppressed comments (1)

docs/scripts/generate-mermaid-sources.mjs:74

• The generator script hard-codes generatedFiles.length !== 11, which will start failing any time a new documentation scenario is added (even if the new .mmd is correctly generated and committed). Instead of a fixed count, compare the generated file list to the committed docs/diagrams/DocumentationSamplesFor*.mmd list and fail on missing/extra files.

[Copilot]

Pull request overview

Copilot reviewed 32 out of 72 changed files in this pull request and generated no new comments.

Suppressed comments (1)

.github/workflows/docs.yml:114

• npm ci was added in the validate job without any npm cache restore in that job. Since GitHub Actions jobs run on fresh runners, the npm cache step in prepare does not benefit validate, so this will likely increase CI time and network usage for every docs PR. Consider adding an npm cache step (or actions/setup-node with npm caching) in validate before running npm ci.

      - name: Install npm dependencies
        run: npm ci # NOSONAR -- Puppeteer's pinned postinstall installs Mermaid CLI's browser.

      - name: Verify Mermaid diagrams
        run: npm run diagrams:check

[Copilot]

Pull request overview

Copilot reviewed 32 out of 72 changed files in this pull request and generated no new comments.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[Copilot]

Pull request overview

Copilot reviewed 32 out of 72 changed files in this pull request and generated no new comments.