docs: explain version calculation and enforce source review

.github/PULL_REQUEST_TEMPLATE.md

@@ -48,5 +48,6 @@ If you're unsure about any of these, don't hesitate to ask. We're here to help!
 * \[ ] My code follows the code style of this project.
 * \[ ] My change requires a change to the documentation.
 * \[ ] I have updated the documentation accordingly.
+* \[ ] I reviewed affected algorithm sections and their review records (see `docs/maintaining-version-calculation.md`).
 * \[ ] I have added tests to cover my changes.
 * \[ ] All new and existing tests passed.

.github/workflows/docs.yml

@@ -143,6 +143,11 @@ jobs:
             docs-inputs-v2-${{ runner.os }}-${{ hashFiles('docs/versions.json') }}-
             docs-inputs-v2-${{ runner.os }}-
 
+      - name: Verify algorithm documentation review records
+        run: |
+          npm run test:algorithm-docs
+          npm run check:algorithm-docs
+
       - name: '[Build Documentation]'
         env:
           GITHUB_TOKEN: ${{ github.token }}

build/common/Utilities/Extensions.cs

@@ -52,9 +52,11 @@ public string GetTaskArguments()
     public static DirectoryPath GetRootDirectory()
     {
         var currentPath = DirectoryPath.FromString(Directory.GetCurrentDirectory());
-        while (!Directory.Exists(currentPath.Combine(".git").FullPath))
+        while (!Directory.Exists(currentPath.Combine(".git").FullPath)
+            && !File.Exists(currentPath.Combine(".git").FullPath))
         {
-            currentPath = currentPath.GetParent();
+            currentPath = currentPath.GetParent()
+                ?? throw new InvalidOperationException("Could not locate the Git repository root.");
         }
 
         return currentPath;

build/docs/Utilities/Mermaid.cs

@@ -61,7 +61,7 @@ public void GenerateMermaidSources(bool check)
                 context.DotNetTest(DocumentationTestsProject.FullPath, new DotNetTestSettings
                 {
                     PathType = DotNetTestPathType.Project,
-                    Filter = "FullyQualifiedName~DocumentationSamplesForGitFlow|FullyQualifiedName~DocumentationSamplesForGitHubFlow|FullyQualifiedName~DocumentationSamplesForTrunkBased",
+                    Filter = "FullyQualifiedName~DocumentationSamplesForGitFlow|FullyQualifiedName~DocumentationSamplesForGitHubFlow|FullyQualifiedName~DocumentationSamplesForTrunkBased|FullyQualifiedName~DocumentationSamplesForVersionCalculation",
                     WorkingDirectory = context.MakeAbsolute(Paths.Root),
                     EnvironmentVariables = new Dictionary<string, string>
                     {

docs/diagrams/DocumentationSamplesForVersionCalculation_CompetingConfiguredAndTaggedVersions_ConfigurationWins.mmd

@@ -0,0 +1,8 @@
+sequenceDiagram
+    main->>main: commit
+    main->>main: tag 1.0.0
+    main->>main: commit
+    rect rgb(211, 211, 211)
+        Note over main: 5.0.0-1
+    end
+    Note over main: next-version: 5.0.0

docs/diagrams/DocumentationSamplesForVersionCalculation_CompetingConfiguredAndTaggedVersions_TagWins.mmd

@@ -0,0 +1,8 @@
+sequenceDiagram
+    main->>main: commit
+    main->>main: tag 1.0.0
+    main->>main: commit
+    rect rgb(211, 211, 211)
+        Note over main: 1.0.1-1
+    end
+    Note over main: next-version: 0.5.0

docs/diagrams/DocumentationSamplesForVersionCalculation_DeploymentModesProcessSameHistory_ContinuousDelivery.mmd

@@ -0,0 +1,8 @@
+sequenceDiagram
+    main->>main: commit
+    main->>main: tag 1.0.0
+    main->>main: commit
+    main->>main: commit
+    rect rgb(211, 211, 211)
+        Note over main: 1.0.1-beta.2
+    end

docs/diagrams/DocumentationSamplesForVersionCalculation_DeploymentModesProcessSameHistory_ContinuousDeployment.mmd

@@ -0,0 +1,8 @@
+sequenceDiagram
+    main->>main: commit
+    main->>main: tag 1.0.0
+    main->>main: commit
+    main->>main: commit
+    rect rgb(211, 211, 211)
+        Note over main: 1.0.1
+    end

docs/diagrams/DocumentationSamplesForVersionCalculation_DeploymentModesProcessSameHistory_ManualDeployment.mmd

@@ -0,0 +1,8 @@
+sequenceDiagram
+    main->>main: commit
+    main->>main: tag 1.0.0
+    main->>main: commit
+    main->>main: commit
+    rect rgb(211, 211, 211)
+        Note over main: 1.0.1-beta.1+2
+    end

docs/diagrams/DocumentationSamplesForVersionCalculation_EqualCandidatesUseLatestSource.mmd

@@ -0,0 +1,11 @@
+sequenceDiagram
+    main->>main: commit
+    main->>main: tag 1.0.0
+    Note over main: Controlled candidate A: 2.0.0 at this commit
+    main->>main: commit
+    Note over main: Controlled candidate B: 2.0.0 at this later commit
+    main->>main: commit
+    Note over main: Equal candidates: 2.0.0 at tag commit and next commit#59; latest source wins
+    rect rgb(211, 211, 211)
+        Note over main: 2.0.0+1
+    end

docs/diagrams/DocumentationSamplesForVersionCalculation_FeatureInheritsSourceIncrement_Minor.mmd

@@ -0,0 +1,10 @@
+sequenceDiagram
+    main->>main: commit
+    main->>main: tag 1.0.0
+    create participant feature_work as feature/work
+    main->>feature_work: branch from main
+    feature_work->>feature_work: commit
+    rect rgb(211, 211, 211)
+        Note over feature_work: 1.1.0-work.1+1
+    end
+    Note over feature_work: main increment: Minor#59; feature increment: Inherit

docs/diagrams/DocumentationSamplesForVersionCalculation_FeatureInheritsSourceIncrement_Patch.mmd

@@ -0,0 +1,10 @@
+sequenceDiagram
+    main->>main: commit
+    main->>main: tag 1.0.0
+    create participant feature_work as feature/work
+    main->>feature_work: branch from main
+    feature_work->>feature_work: commit
+    rect rgb(211, 211, 211)
+        Note over feature_work: 1.0.1-work.1+1
+    end
+    Note over feature_work: main increment: Patch#59; feature increment: Inherit

docs/diagrams/DocumentationSamplesForVersionCalculation_MergeMessageAndCountingSourceDiffer.mmd

@@ -0,0 +1,11 @@
+sequenceDiagram
+    main->>main: commit
+    main->>main: tag 1.0.0
+    create participant release_2_0_0 as release/2.0.0
+    main->>release_2_0_0: branch from main
+    release_2_0_0->>release_2_0_0: commit
+    release_2_0_0->>main: merge
+    main->>main: commit
+    rect rgb(211, 211, 211)
+        Note over main: 2.0.0-3
+    end

docs/diagrams/VersionCalculation_DeploymentModes.mmd

@@ -0,0 +1,10 @@
+flowchart TD
+    Candidate["Selected candidate and resolved sources"] --> Mode{"Deployment mode"}
+    Mode -->|ManualDeployment| Manual["Keep candidate prerelease state<br/>Attach build metadata"]
+    Mode -->|ContinuousDelivery| Numbered{"Numbered prerelease present?"}
+    Numbered -->|No| Error["Error: prerelease tag required"]
+    Numbered -->|Yes| Delivery["Prerelease number +=<br/>commits since source - 1<br/>Record source distance"]
+    Mode -->|ContinuousDeployment| Deployment["Remove prerelease tag<br/>Record source distance"]
+    Manual --> Floor["Check eligible branch-tag numeric version floor"]
+    Delivery --> Floor
+    Deployment --> Floor

docs/diagrams/VersionCalculation_Inheritance.mmd

@@ -0,0 +1,15 @@
+flowchart TD
+    Branch["Branch configuration"] --> Inherit{"Increment is Inherit?"}
+    Inherit -->|No| Effective["Effective configuration"]
+    Inherit -->|Yes| PR{"Allowed pull-request target<br/>identified from merge context?"}
+    PR -->|Yes| Target["Use target as source branch"]
+    PR -->|No| Sources["Find allowed source branches"]
+    Sources --> Found{"Source branches found?"}
+    Found -->|Yes| Recursive["Recursively inherit configuration<br/>with cycle guard"]
+    Target --> Recursive
+    Recursive --> Results["Zero, one or multiple<br/>effective configurations"]
+    Found -->|No| Global{"Global increment is Inherit?"}
+    Global -->|Yes| Skip["Skip orphaned branch"]
+    Global -->|No| Fallback["Use global fallback configuration"]
+    Effective --> Results
+    Fallback --> Results

docs/diagrams/VersionCalculation_Mainline.mmd

@@ -0,0 +1,10 @@
+flowchart TD
+    Enabled["Mainline enabled"] --> Tags["Gather eligible tags and branch context"]
+    Tags --> Traverse["Traverse commits;<br/>inspect branch points and merges"]
+    Traverse --> State["Build commit state and recursive iterations"]
+    State --> Pre["Enrich version and increment context"]
+    Pre --> Rules["Apply matching trunk/non-trunk rules"]
+    Rules --> Post["Clean up context after each commit"]
+    Post --> Fold["Fold baseline operands<br/>and increment operators"]
+    Fold --> Candidate["Mainline candidate enters shared selection"]
+    Traverse --> Unsupported["Recognized merge between two main branches:<br/>currently unsupported"]

docs/diagrams/VersionCalculation_Overview.mmd

@@ -0,0 +1,16 @@
+flowchart TD
+    Context["Current commit, branch and configuration"] --> Config["Resolve branch configuration"]
+    Config --> Tagged{"Matching current-commit tag,<br/>resolved increment and<br/>prevent increment when tagged?"}
+    Tagged -->|Yes| TagResult["Use tag and build metadata"]
+    Tagged -->|No| Inherit["Resolve effective configurations<br/>including branch inheritance"]
+    Inherit --> Candidates["Collect and increment strategy candidates"]
+    Candidates --> Any{"Any accepted candidates?"}
+    Any -->|No| Error["No base versions: error"]
+    Any -->|Yes| Select["Select maximum incremented SemVer<br/>Resolve ties and count source"]
+    Select --> InheritedTag{"Inherited increment resolved;<br/>matching current tag and<br/>prevent increment when tagged?"}
+    InheritedTag -->|Yes| TagResult
+    InheritedTag -->|No| Mode["Apply deployment mode"]
+    Mode --> Floor["Raise numeric version if<br/>an eligible branch tag is higher"]
+    Floor --> Result["Semantic version and source metadata"]
+    TagResult --> Result
+    Result --> Output["Version variables and output formatting"]

docs/diagrams/VersionCalculation_Selection.mmd

@@ -0,0 +1,15 @@
+flowchart TD
+    Pool["All accepted incremented candidates"] --> Maximum["Find maximum SemVer"]
+    Maximum --> Tie{"Multiple source-backed candidates<br/>produce this same version?"}
+    Tie -->|Yes| Latest["Latest source timestamp chooses<br/>winner and count source"]
+    Tie -->|No| Winner["Keep maximum semantic candidate"]
+    Winner --> Stable{"Winning version is stable?"}
+    Stable -->|Yes| Exclude["Exclude prerelease baselines<br/>from count-source search"]
+    Stable -->|No| Count["Prefer source-backed candidate:<br/>highest incremented version,<br/>then latest source timestamp"]
+    Exclude --> Count
+    Count --> Found{"Source-backed candidate found?"}
+    Found -->|Yes| Anchor["Use its source as counting anchor"]
+    Found -->|No| External["Use highest remaining external candidate:<br/>null counting anchor"]
+    Latest --> Resolved["Resolved semantic and counting sources"]
+    Anchor --> Resolved
+    External --> Resolved

docs/diagrams/VersionCalculation_Strategies.mmd

@@ -0,0 +1,20 @@
+flowchart TD
+    Config["One effective configuration"] --> Strategies["Evaluate enabled non-fallback strategies"]
+    Strategies --> Configured["ConfiguredNextVersion<br/>Configured next-version"]
+    Strategies --> Tagged["TaggedCommit<br/>Eligible tags"]
+    Strategies --> Merge["MergeMessage<br/>Release merge messages"]
+    Strategies --> Name["VersionInBranchName<br/>Release branch name"]
+    Strategies --> Release["TrackReleaseBranches<br/>Related release targets"]
+    Strategies --> Mainline["Mainline<br/>Commit and merge traversal"]
+    Configured --> Filter["Ignore filters and candidate increment"]
+    Tagged --> Filter
+    Merge --> Filter
+    Name --> Filter
+    Release --> Filter
+    Mainline --> Filter
+    Filter --> Any{"Any accepted candidate<br/>from these strategies?"}
+    Any -->|Yes| Pool["Add candidates to global comparison"]
+    Any -->|No| Enabled{"Fallback enabled?"}
+    Enabled -->|Yes| Fallback["Fallback candidate:<br/>apply filters and increment"]
+    Fallback --> Pool
+    Enabled -->|No| None["No candidate from this configuration"]

docs/input/Shared/Sidebar/_ChildPages.cshtml

@@ -25,7 +25,7 @@
         var groups = new[] {
             Tuple.Create("Getting started", "/docs/getting-started", new[] { "/docs/getting-started", "/docs/usage/cli/installation", "/docs/reference/requirements" }),
             Tuple.Create("Guides", "/docs/usage", new[] { "/docs/usage/choose-workflow", "/docs/usage/configure", "/docs/learn/branching-strategies", "/docs/reference/build-servers", "/docs/usage/cli/output", "/docs/usage/docker", "/docs/usage/msbuild", "/docs/usage/cli/assembly-patch", "/docs/usage/library", "/docs/learn/dynamic-repositories" }),
-            Tuple.Create("Concepts", "/docs/learn", new[] { "/docs/learn/intro-to-semver", "/docs/learn/how-it-works", "/docs/learn/workflows-modes-strategies", "/docs/reference/modes", "/docs/reference/version-increments" }),
+            Tuple.Create("Concepts", "/docs/learn", new[] { "/docs/learn/intro-to-semver", "/docs/learn/how-it-works", "/docs/learn/version-calculation", "/docs/learn/workflows-modes-strategies", "/docs/reference/modes", "/docs/reference/version-increments" }),
             Tuple.Create("Reference", "/docs/reference", new[] { "/docs/reference/configuration-topics", "/docs/usage/cli/arguments", "/docs/reference/version-sources", "/docs/reference/variables", "/docs/reference/custom-formatting", "/docs/reference/environment-variables" }),
             Tuple.Create("Troubleshooting", "/docs/learn/faq", new[] { "/docs/learn/faq", "/docs/learn/git-setup" }),
             Tuple.Create("Upgrading", "/docs/migration", new[] { "/docs/migration/v6-to-v7" })

docs/input/assets/css/redesign.css

@@ -239,6 +239,20 @@ body.layout-top-nav .content-wrapper, body.layout-top-nav .main-footer { margin-
 .content .card-header img { filter: brightness(.5); max-width: 25px; }
 .content .btn-primary { border-radius: 5px; background: var(--gv-purple); border-color: var(--gv-purple); padding: 9px 14px; }
 .mermaid { overflow: auto; max-width: 100%; }
+/* Mermaid's embedded flowchart styles retain light-theme connector colors. */
+html[data-theme="dark"] .mermaid .flowchart-link { stroke: #b1bac4 !important; }
+html[data-theme="dark"] .mermaid .marker { fill: #b1bac4 !important; stroke: #b1bac4 !important; }
+html[data-theme="dark"] .mermaid .actor-line,
+html[data-theme="dark"] .mermaid .messageLine0,
+html[data-theme="dark"] .mermaid .messageLine1 { stroke: #b1bac4 !important; }
+html[data-theme="dark"] .mermaid .messageText { fill: #f0f6fc !important; }
+html[data-theme="dark"] .mermaid marker[id$="-arrowhead"] path,
+html[data-theme="dark"] .mermaid marker[id$="-filled-head"] path,
+html[data-theme="dark"] .mermaid marker[id$="-solidTopArrowHead"] path,
+html[data-theme="dark"] .mermaid marker[id$="-solidBottomArrowHead"] path { fill: #b1bac4 !important; stroke: #b1bac4 !important; }
+html[data-theme="dark"] .mermaid marker[id$="-crosshead"] path,
+html[data-theme="dark"] .mermaid marker[id$="-stickTopArrowHead"] path,
+html[data-theme="dark"] .mermaid marker[id$="-stickBottomArrowHead"] path { stroke: #b1bac4 !important; }
 #return-to-top { background: var(--gv-purple); border-radius: 6px; right: 20px; bottom: 20px; }
 @media (min-width: 1441px) {
     body.layout-boxed { background: #f7f6f9; }

docs/input/docs/learn/how-it-works.md

@@ -5,6 +5,10 @@ RedirectFrom: docs/more-info/how-it-works
 ---
 GitVersion combines repository history with effective configuration to calculate a version for the current commit. It then exposes that result as [version variables][version-variables].
 
+Follow the [version calculation algorithm][version-calculation-algorithm] for
+decision diagrams covering all strategies, candidate selection, inheritance,
+Mainline, deployment modes, and versioning scenario families.
+
 <a id="architecture"></a>
 
 ## 1. Resolve the context and configuration
@@ -60,3 +64,5 @@ If your output is unexpected, follow [Troubleshooting][troubleshooting] before c
 [gitflow-examples]: /docs/learn/branching-strategies/gitflow/examples
 
 [troubleshooting]: /docs/learn/faq
+
+[version-calculation-algorithm]: /docs/learn/version-calculation

docs/input/docs/learn/index.cshtml

@@ -9,6 +9,7 @@ RedirectFrom: docs/more-info
 <li><a href="/docs/learn/intro-to-semver">Semantic versioning</a> — version numbers, pre-release labels, and metadata.</li>
 <li><a href="/docs/learn/workflows-modes-strategies">Workflows, deployment modes, and strategies</a> — three different configuration choices.</li>
 <li><a href="/docs/learn/how-it-works">How versions are calculated</a> — from repository history to output.</li>
+<li><a href="/docs/learn/version-calculation">Version calculation algorithm</a> — decision diagrams for strategies, selection, and scenario families.</li>
 <li><a href="/docs/reference/modes">Deployment modes</a> — how versions behave between releases.</li>
 <li><a href="/docs/reference/version-increments">Version increments</a> — tags, branch rules, and commit messages.</li>
 </ol>