docs: explain version calculation and enforce source review

[arturcic]

Description

Closes #5300.

Explain the current version-calculation pipeline with six authored Mermaid flowcharts covering strategy candidates, branch inheritance, increments, selection/counting sources, Mainline, and deployment modes. Add navigation, a table of contents, and eleven test-generated histories, including nine new worked examples backed by ten cases that assert versions and source metadata.

Require an explicit section review when mapped calculation sources change. Add a section manifest, a read-only checker with reviewed acknowledgements, contributor guidance, and CI integration. Fix Mermaid DOM initialization, linked-worktree root detection, and dark-theme diagram contrast; remove the unused legacy calculation diagram.

Validation

• Rebased onto origin/main at fe248d7765f280749a2bc97cff17eeb22c19f92c; current PR head is ce9f9e4f270ae47b2db2b060213e5960271dae2f. Fresh local documentation validation passed (58 passed, 0 failed, 0 skipped); all 26 generated sources matched and all 32 Mermaid diagrams validated. Fresh CI and hosted reviews for this rebased head passed: Actions run 38164210299 completed successfully on attempt 1; Sonar reports zero new issues and no annotations; CodeRabbit covered this exact head with no actionable comments; Copilot reports zero open findings. All inline threads are resolved.
• 13 checker tests passed; seven section review records verified.
• Full versioned documentation build passed, including all 58 generated-example cases.
• Regeneration matched all 26 test-generated sources; all 32 Mermaid sources passed syntax validation.
• Scoped Markdown/reference-link checks, actionlint, and diff checks passed.
• Browser audit rendered every Mermaid occurrence across 513 documentation/API pages in both themes. The nine added worked examples were also checked in both themes. Screenshots of the original eight page diagrams are in the comments.
• Before rebasing, GitHub Actions passed at 83a9764f1bcfa9ee6533616a53f610555c889003, including the platform/backend test matrix, packaging, artifact/Docker checks, documentation, formatting, and CodeQL: run 37967168231.
• The unchanged local-HTTP clone test failed in the first Windows managed attempt and passed on a focused rerun. No assertions were changed for that rerun.
• Pre-rebase reviews at 83a9764f1: Sonar passed with zero new issues and no annotations; CodeRabbit completed with no actionable comments; Copilot reported zero open findings. Its fixture-parallelism finding was fixed and resolved.

The algorithm flowcharts remain manually authored. The source checker enforces review, not semantic correctness; the generated histories provide representative executable checkpoints.

Summary by CodeRabbit

• Documentation
  • Added a guide with diagrams and examples explaining version calculation, including strategies, branch inheritance, candidate selection, and deployment modes.
  • Linked the guide from learning and reference pages, and added guidance for reviewing and maintaining its content.
  • Added examples covering competing version sources, inherited increments, and deployment modes; improved diagram readability in dark mode.
• Tests
  • Added checks to verify the guide stays aligned with version-calculation behavior.
  • Documentation validation now runs as part of the standard checks.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: 8bc83774-61cf-47f8-8926-1866a96f52d2

---

---

---

📥 Commits

Reviewing files that changed from the base of the PR and between 83a9764 and ce9f9e4.

---

---

---

⛔ Files ignored due to path filters (1)

• package-lock.json is excluded by !**/package-lock.json

---

---

---

📒 Files selected for processing (1)

• docs/scripts/check-version-calculation.test.mjs

---

---

---

Included review availability: This review used your included allowance. Your plan provides up to 8 included reviews per hour; 6 remain after this review.

---

---

---

---

📝 Walkthrough

📝 Walkthrough

📝 Walkthrough

📝 Walkthrough

Walkthrough

The pull request adds a version-calculation guide with diagrams and test-derived examples. It adds source review records and a checker that validates their coverage and fingerprints. Package scripts and the documentation workflow run the checks.

Changes

Version calculation documentation

Layer / File(s)	Summary
Algorithm guide and decision diagrams docs/input/docs/learn/version-calculation.md, docs/diagrams/VersionCalculation_*.mmd, docs/diagrams/version-calculation.mmd, docs/input/docs/learn/how-it-works.md, docs/input/docs/reference/version-sources.md, docs/input/Shared/Sidebar/_ChildPages.cshtml, docs/input/docs/learn/index.cshtml, docs/input/assets/css/redesign.css	The guide describes calculation stages, and the diagrams illustrate candidate strategies, inheritance, selection, Mainline, and deployment modes. Learning and reference pages link to the guide.
Scenario map and executable examples docs/input/docs/learn/version-calculation.md, src/GitVersion.Core.Tests/IntegrationTests/DocumentationSamplesForVersionCalculation.cs, docs/diagrams/DocumentationSamplesForVersionCalculation_*.mmd, build/docs/Utilities/Mermaid.cs	The guide maps versioning scenarios and test-derived examples. Integration tests assert version and source metadata for several histories and generate diagrams. The Mermaid generator includes these tests in its filter.
Source mapping and review records docs/version-calculation-map.json, docs/scripts/check-version-calculation.mjs, docs/scripts/check-version-calculation.test.mjs, docs/maintaining-version-calculation.md, .github/PULL_REQUEST_TEMPLATE.md, docs/input/docs/learn/version-calculation.md	The map links guide sections to sources and evidence. The checker validates the map, source coverage, and review fingerprints. The maintenance guide and pull request template describe review-record updates.
Documentation validation wiring package.json, docs/scripts/validate-mermaid.mjs, .github/workflows/docs.yml	Package scripts and the documentation workflow run the algorithm documentation checks and tests. Mermaid validation creates a DOM before importing Mermaid.

Repository root discovery

Layer / File(s)	Summary
Repository root discovery behavior build/common/Utilities/Extensions.cs	GetRootDirectory recognizes .git as a file or directory and throws InvalidOperationException if the search reaches a path without a parent before finding either.

Priority: ➖ Normal

Estimated code review effort: 4 (Complex) | ~45 minutes

Change: Other · Severity of issue fixed: Medium

---

---

---

---

---

---

---

Merge Risk: ⚪ Minimal · up to ce9f9

No merge-blocking issue is identified in the reviewed change.

Pre-merge checks | 4 | 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 14 functions across 6 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check		The PR satisfies the coding requirements in [#5300]. It adds navigable Mermaid diagrams and documentation for strategy discovery, inherited configuration, increments, candidate and source selection, M…
Out of Scope Changes check		The changes remain within [#5300]. Workflow and package-script changes run the required documentation checks. Root detection, Mermaid initialization, dark-theme styling, navigation, contributor guidan…
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly and concisely describes the pull request's two main changes: documenting version calculation and enforcing source review.

---

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

---

---

---

---

---

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

---

_{Comment @coderabbitai help to get the list of available commands.}

[arturcic]

Rendered Mermaid previews for source head 61fc6dae6. Both themes use the built documentation styles.

Calculation overview — light/dark

Light	Dark

Calculation strategies — light/dark

Light	Dark

[arturcic]

Rendered Mermaid previews for source head 61fc6dae6. Both themes use the built documentation styles.

Branch inheritance — light/dark

Light	Dark

Candidate selection and sources — light/dark

Light	Dark

[arturcic]

Rendered Mermaid previews for source head 61fc6dae6. Both themes use the built documentation styles.

Mainline traversal — light/dark

Light	Dark

Deployment modes — light/dark

Light	Dark

[arturcic]

Rendered Mermaid previews for source head 61fc6dae6. Both themes use the built documentation styles.

Test-generated release-tag history — light/dark

Light	Dark

Test-generated commit-message increments — light/dark

Light	Dark

[arturcic]

Added in e6111ee9f: executable worked examples on the version-calculation page. Ten new test cases generate nine Mermaid histories covering competing configured/tag candidates, inherited Patch/Minor increments, equal-version ties, separate semantic and counting sources, and all three deployment modes.

The examples assert full versions and source metadata. The tie case supplies controlled strategy candidates in both enumeration orders to isolate the timestamp selection rule; the other histories use normal strategy discovery. The generator now includes this sample family, and the maintenance guide and source-to-section map point to the new evidence.

Validation:

• Full documentation build passed: 58 tests succeeded, 0 failed, 0 skipped, including the ten new cases.
• Generation followed by build verification matched all 26 generated Mermaid sources; all 32 Mermaid sources passed syntax validation.
• All 13 documentation safeguard tests passed; all seven source-review records validated. Reference-link checks reported zero violations across 65 Markdown files; scoped Markdown lint and diff checks passed.
• The nine new diagrams rendered in both light and dark themes in the browser, with readable shared arrow and label colors.

These are representative checkpoints. The algorithm flowcharts remain manually authored and still require review when calculation rules change. CodeRabbit review was attempted but remains blocked by its organization-membership service error.

[arturcic]

@coderabbitai full review

Please review the full current PR, including the documentation source-review guard and generated calculation examples. This draft is awaiting your review before it is marked ready.

[coderabbitai]

✅ Action performed

Full review finished.

[arturcic]

Addressed the 18 Sonar annotations in check-version-calculation.mjs: use explicit error construction, remove the unused path import, use a prefix check for headings, and specify a path comparator while preserving the previous UTF-16 lexical ordering.

All 13 checker tests pass, the existing source hashes still validate for all seven sections, and the diff check passes. The preceding running build is canceled before this push; CI and reviews will be checked again on the new head.

[Copilot]

🔵 Needs a closer look

The extensive manually authored algorithm semantics require final domain-expert verification despite the strong automated safeguards.

0 open findings

What changed in this PR

Documents GitVersion’s version-calculation pipeline and adds safeguards that require algorithm documentation review when mapped implementation sources change.

Changes:

• Adds authored Mermaid flowcharts and test-generated examples.
• Adds source-to-section review manifests, validation, tests, and CI enforcement.
• Improves Mermaid validation, dark-theme rendering, navigation, and worktree detection.

File	Description
src/​GitVersion.Core.Tests/​IntegrationTests/​DocumentationSamplesForVersionCalculation.cs	Adds executable documentation scenarios.
package.json	Adds checker commands and JSDOM.
package-lock.json	Locks JSDOM dependencies.
docs/​version-calculation-map.json	Maps documentation sections to sources.
docs/​scripts/​validate-mermaid.mjs	Initializes Mermaid with a DOM.
docs/​scripts/​check-version-calculation.test.mjs	Tests review enforcement.
docs/​scripts/​check-version-calculation.mjs	Implements source-review validation.
docs/​maintaining-version-calculation.md	Documents the review workflow.
docs/​input/​Shared/​Sidebar/​_ChildPages.cshtml	Adds sidebar navigation.
docs/​input/​docs/​reference/​version-sources.md	Links the algorithm guide.
docs/​input/​docs/​learn/​version-calculation.md	Adds the algorithm documentation.
docs/​input/​docs/​learn/​index.cshtml	Adds the learning-page link.
docs/​input/​docs/​learn/​how-it-works.md	Links detailed calculation guidance.
docs/​input/​assets/​css/​redesign.css	Improves dark-theme Mermaid contrast.
docs/​diagrams/​VersionCalculation_Strategies.mmd	Diagrams strategy discovery.
docs/​diagrams/​VersionCalculation_Selection.mmd	Diagrams candidate selection.
docs/​diagrams/​VersionCalculation_Overview.mmd	Diagrams the overall pipeline.
docs/​diagrams/​VersionCalculation_Mainline.mmd	Diagrams Mainline traversal.
docs/​diagrams/​VersionCalculation_Inheritance.mmd	Diagrams branch inheritance.
docs/​diagrams/​VersionCalculation_DeploymentModes.mmd	Diagrams deployment modes.
docs/​diagrams/​version-calculation.mmd	Removes the legacy diagram.
docs/​diagrams/​DocumentationSamplesForVersionCalculation_MergeMessageAndCountingSourceDiffer.mmd	Adds merge-source example.
docs/​diagrams/​DocumentationSamplesForVersionCalculation_FeatureInheritsSourceIncrement_Patch.mmd	Adds patch inheritance example.
docs/​diagrams/​DocumentationSamplesForVersionCalculation_FeatureInheritsSourceIncrement_Minor.mmd	Adds minor inheritance example.
docs/​diagrams/​DocumentationSamplesForVersionCalculation_EqualCandidatesUseLatestSource.mmd	Adds candidate tie example.
docs/​diagrams/​DocumentationSamplesForVersionCalculation_DeploymentModesProcessSameHistory_ManualDeployment.mmd	Adds manual-mode example.
docs/​diagrams/​DocumentationSamplesForVersionCalculation_DeploymentModesProcessSameHistory_ContinuousDeployment.mmd	Adds continuous-deployment example.
docs/​diagrams/​DocumentationSamplesForVersionCalculation_DeploymentModesProcessSameHistory_ContinuousDelivery.mmd	Adds continuous-delivery example.
docs/​diagrams/​DocumentationSamplesForVersionCalculation_CompetingConfiguredAndTaggedVersions_TagWins.mmd	Adds tag-winner example.
docs/​diagrams/​DocumentationSamplesForVersionCalculation_CompetingConfiguredAndTaggedVersions_ConfigurationWins.mmd	Adds configuration-winner example.
build/​docs/​Utilities/​Mermaid.cs	Generates the new examples.
build/​common/​Utilities/​Extensions.cs	Supports linked-worktree roots.
.github/​workflows/​docs.yml	Enforces review records in CI.
.github/​PULL_REQUEST_TEMPLATE.md	Adds the review checklist item.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[arturcic]

@coderabbitai full review

Please review current head 5fd34b30de3b65e201839e86731d87d8cc8a9123. The Sonar checker findings have been fixed and the new quality gate passes. Keep this draft under review until the full PR has no actionable findings.

[coderabbitai]

✅ Action performed

Full review finished.

[Copilot]

🟡 Changes recommended

The timestamp-sensitive documentation fixture can race the repository’s shared test clock under fixture-level parallel execution.

1 open finding

• Disable parallelism for fixture using unsynchronized virtual time · New

🧠 Review effort: Balanced

[arturcic]

@coderabbitai review

Please review current head 83a9764f1bcfa9ee6533616a53f610555c889003. It isolates the timestamp-sensitive example fixture after Copilot identified the shared-clock race. All 58 documentation cases and generated-diagram checks pass.

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[Copilot]

🔵 Needs a closer look

The extensive hand-authored algorithm descriptions and diagrams require final validation by a version-calculation domain owner.

0 open findings

1 resolved since last review

• Disable parallelism for fixture using unsynchronized virtual time

🧠 Review effort: Balanced

[arturcic]

Marked ready for review after validating current head 83a9764f1bcfa9ee6533616a53f610555c889003.

• GitHub Actions run 37967168231 succeeded. The Windows managed job passed on its focused rerun after the unchanged local-HTTP clone test failed in the first attempt.
• Sonar: zero new issues and no annotations.
• CodeRabbit: current head reviewed, no actionable comments. Its default docstring-coverage warning is advisory and is not a required repository gate or a functional finding.
• Copilot: zero open findings. The shared-clock race was fixed by making the timestamp-sensitive example fixture non-parallel; its thread is resolved.
• Local documentation validation: 58 passed, 0 failed, 0 skipped; all 26 generated sources matched and all 32 Mermaid sources validated.

Copilot's request for domain-owner validation of the authored algorithm descriptions remains part of the normal human review. The PR closes #5300, assigned to milestone 7.0.x.

[arturcic]

Rebased onto latest origin/main (fe248d7765f280749a2bc97cff17eeb22c19f92c) and pushed ce9f9e4f270ae47b2db2b060213e5960271dae2f to the fork using a fresh explicit force-with-lease.

The four logical PR commits are preserved. Range-diff shows unchanged patches except removal of one extra blank line at EOF in the checker test file. Ancestry, whitespace, and worktree checks pass.

Validation: 13 checker tests passed; seven algorithm review records verified; ValidateMermaidDiagrams passed 58 documentation cases (0 failed, 0 skipped), matched all 26 generated sources, and validated all 32 Mermaid sources.

CI and hosted review are running on the rebased head; the previous green results apply to the pre-rebase head.

[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]

🔵 Needs a closer look

The broad hand-authored algorithm description and diagrams require final human verification of semantic accuracy.

0 open findings

🧠 Review effort: Balanced

[arturcic]

Rebased head ce9f9e4f270ae47b2db2b060213e5960271dae2f is green again.

• Full Actions run 38164210299 passed on attempt 1, including all six platform/backend test jobs. Current checks: 35 successful, four intentionally skipped, two neutral; no pending or failed checks.
• Sonar quality gate passed with zero new issues and no annotations.
• CodeRabbit reviewed this exact head and generated no actionable comments.
• Fresh Copilot review reports zero open findings. There are no unresolved inline threads.
• Local rebase validation passed: 58 documentation cases, 26 matching generated sources, 32 valid Mermaid sources, and 13 checker tests.

No additional source changes, CI cancellations, or pushes were needed. The existing workflow/platform warnings and dependency scorecard advisories are non-blocking; CodeRabbit's generic docstring coverage advisory remains outside the repository's required gates. Copilot's request for human verification of the authored algorithm semantics remains part of normal review.

The PR remains ready for review, closes #5300 in milestone 7.0.x, and has not been merged. Pausing the follow-up monitor now that the current-head checks and requested bot reviews are complete.