[arturcic]

Updated by Codex on behalf of @arturcic.

Description

Closes #5300.

Explain the v7 version-calculation pipeline with six authored Mermaid flowcharts covering strategy discovery, inherited configuration, candidate selection and counting sources, Mainline traversal, and deployment modes. Add navigation and eleven test-generated histories, including nine new worked examples backed by ten test cases asserting versions and source metadata.

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

The source checker enforces review rather than proving prose or diagram semantics. Generated histories are representative executable checkpoints; broader algorithm tests remain the executable catalogue.

Validation and remaining work

Current PR head: 31a5d9c40a653b2067a6a3bf55be4d1a33106deb, rebased onto upstream main at 5153cb1735862081ad0fdf10b51184f581d7cdc2.

The conflict-free rebase preserved all five prior commits unchanged, verified with range-diff. The algorithm source-review guard still verifies all seven records. Follow-up commit 31a5d9c40 resolves eight Mermaid css:S9423 findings by adding a stable content-wrapper ID and increasing selector specificity, removing the flagged !important declarations while preserving both themes. This PR remains independent of #5295.

Fresh validation for this exact head:

• Full CI run 38716301228 passed on attempt 1, including all six platform/backend test jobs, packaging, artifacts, Docker, and package checks.
• Documentation CI run 38716301042 passed, including the review guard, full documentation build, HTML validation, and Markdown lint. Publishing was skipped for PR validation.
• Current checks: 35 successful, four skipped, two neutral; no pending or failed checks.
• Sonar quality gate passed with zero new issues and no annotations.
• Local .NET SDK 10.0.402: full BuildDocs passed; 58 documentation cases passed, 0 failed, 0 skipped; all 26 generated Mermaid sources matched and all 32 diagrams validated. Checker tests: 13 passed, 0 failed, 0 skipped; all seven review records verified.
• Browser verification: all 17 algorithm-page diagrams rendered; dark-theme connectors/arrows retain #b1bac4 and message text retains #f0f6fc; light-theme colors remain unchanged.
• CodeRabbit CLI: committed PR diff and the subsequent two-file specificity fix both reviewed with zero findings. Hosted CodeRabbit is paused; its status is not counted as a fresh hosted review.
• No unresolved inline review threads. Fresh Copilot review could not complete because the requesting account reached its quota; earlier Copilot reviews do not validate this final head.
• git diff --check, upstream ancestry, and clean-worktree checks passed. Superseded run 38715050331 was fully cancelled before pushing the follow-up fix.

Human approval and semantic review of the authored algorithm descriptions remain required. The PR is ready for review and has not been merged.

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

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

• Last reviewed commit: 5d7b52e
• Latest commit, not reviewed: 31a5d9c

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: 0b453150-5cb9-47c9-aa74-41f3d57d5cd7

📥 Commits

Reviewing files that changed from the base of the PR and between 53a35ba and 5d7b52e.

📒 Files selected for processing: 1

• docs/version-calculation-map.json

🚧 Files skipped from review as they are similar to previous changes: 1

• docs/version-calculation-map.json

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

📝 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 5d7b5

The review records do not currently block documentation validation. Complete the planned human review and normal documentation checks before merging.

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. (1 skipped: 1…	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks: 4 passed

Check name	Status	Explanation
Linked Issues check		The pull request meets the coding requirements in [#5300]. The new version-calculation page and six authored Mermaid diagrams cover strategy discovery, inherited configuration, candidate increments, s…
Out of Scope Changes check		The changes stay within [#5300]. Workflow and package scripts enforce the documentation checks. GetRootDirectory supports linked worktrees used by the checks. Mermaid initialization, dark-theme CSS,…
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly and concisely summarizes the pull request's main changes: documenting version calculation and enforcing source review.

Full details: Docstring Coverage

Explanation

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. (1 skipped: 1 unsupported.)

• 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.

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

[arturcic]

Rebased onto latest origin/main (5153cb1735862081ad0fdf10b51184f581d7cdc2) and pushed ead8f7570968acff00b64ea35b23320502331c10 to the fork with an explicit force-with-lease.

Range-diff confirms all five PR commits are unchanged. All seven source-review records remain valid. Local checks passed: 13 checker tests, 58 documentation cases (0 failed, 0 skipped), 26 matching generated sources, and 32 valid Mermaid diagrams. Local CodeRabbit review of the committed diff against origin/main completed with zero findings.

No old-head runs were active before the push. Fresh main CI and documentation CI are running; I am following their results on this exact head.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[arturcic]

Fixed the eight Mermaid CSS specificity findings in 31a5d9c40a653b2067a6a3bf55be4d1a33106deb.

Mermaid embeds color rules scoped to generated SVG IDs, so class-only selectors previously needed !important. The layout now gives its content wrapper a stable gv-content ID; the dark-theme selectors use that ID to outrank Mermaid's rules naturally. Removed all eight flagged !important declarations without suppressing Sonar.

Validation: full BuildDocs succeeded; 58 documentation tests passed with no failures or skips, 26 generated sources matched, and 32 diagrams validated. Browser inspection confirmed all 17 algorithm-page diagrams render, dark-theme connector/arrow colors remain #b1bac4, message text remains #f0f6fc, and light-theme colors remain unchanged. CodeRabbit reviewed the two-file fix and reported zero findings.

Verified superseded run 38715050331 completed as cancelled before pushing. Fresh CI is running on the new head. Copilot could not perform its requested rebased-head review because the requesting account has reached its quota.

[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

[arturcic]

Rebase and CI follow-up complete at 31a5d9c40a653b2067a6a3bf55be4d1a33106deb, based on origin/main at 5153cb1735862081ad0fdf10b51184f581d7cdc2.

• Full CI and documentation CI passed on this exact head. All six platform/backend test jobs passed; no reruns were needed for this final head.
• 35 successful checks, four skipped, two neutral; none failed or pending.
• Sonar: zero new issues, no annotations. The eight Mermaid CSS findings are resolved through selector specificity, with both themes verified in the browser.
• CodeRabbit CLI: zero findings for the committed PR diff and for the follow-up fix. No unresolved review threads.

Fresh Copilot review remains unavailable due to the requesting account's quota; hosted CodeRabbit is paused. These are not represented as completed current-head hosted reviews.

The worktree is clean, the PR remains ready for review, and #5295 was not incorporated. Pausing the CI follow-up monitor. No merge performed.

[mergify]

Thank you @arturcic for your contribution!