Merge pull request #4104 from arturcic/feature/4017

Keep `configuration.md` file in sync with the changes in code

Author: arturcic

.github/workflows/docs.yml

@@ -110,7 +110,7 @@ jobs:
       uses: chabad360/htmlproofer@master
       with:
         directory: ./artifacts/docs/preview
-        arguments: --ignore-urls /api/,/docs/ --allow-hash-href --assume-extension --disable-external --no-check_external_hash
+        arguments: --ignore-urls /api/,/docs/ --allow-hash-href --allow-missing-href --assume-extension --disable-external --no-check_external_hash
     -
       name: '[Reviewdog Reporter]'
       id: reporter

.github/workflows/mkdocs.yml

@@ -0,0 +1,42 @@
+name: Markdown Update
+on:
+  push:
+
+env:
+  DOTNET_ROLL_FORWARD: "Major"
+  DOTNET_CLI_TELEMETRY_OPTOUT: 1
+  DOTNET_SKIP_FIRST_TIME_EXPERIENCE: 1
+  DOTNET_NOLOGO: 1
+  
+defaults:
+  run:
+    shell: pwsh
+    
+jobs:
+  docs:
+    name: Update Markdown (embedded snippets)
+    runs-on: ubuntu-latest
+    steps:
+      -
+        name: Checkout
+        uses: actions/checkout@v4
+      - 
+        name: Run MarkdownSnippets
+        run: |
+          dotnet tool install --global MarkdownSnippets.Tool
+          mdsnippets --write-header false
+        working-directory: ${{ github.workspace }}/docs/input
+      - 
+        name: Check for changes
+        id: status
+        run: |
+          if ($null -ne (git status --porcelain)) { echo "has_changes=1"; echo "has_changes=1" >> $env:GITHUB_OUTPUT }
+      - 
+        name: Push changes
+        run: |
+          git add --verbose .
+          git config user.name 'Artur Stolear'
+          git config user.email '[email protected]'
+          git commit -m 'Docs changes' --allow-empty
+          git push --force
+        if: steps.status.outputs.has_changes == '1'

build/CI.sln

@@ -42,6 +42,7 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "workflows", "workflows", "{
 		..\.github\workflows\_unit_tests.yml = ..\.github\workflows\_unit_tests.yml
 		..\.github\workflows\stale.yml = ..\.github\workflows\stale.yml
 		..\.github\workflows\winget.yml = ..\.github\workflows\winget.yml
+		..\.github\workflows\mkdocs.yml = ..\.github\workflows\mkdocs.yml
 		..\.github\dependabot.yml = ..\.github\dependabot.yml
 	EndProjectSection
 EndProject

build/docs/BuildLifetime.cs

@@ -20,14 +20,18 @@ public override void Setup(BuildContext context, ISetupContext info)
             Theme = "Samson",
             OutputPath = context.MakeAbsolute(Paths.ArtifactsDocs.Combine("preview")),
             RootPath = context.MakeAbsolute(Paths.Docs),
-            ConfigurationFile = context.MakeAbsolute(Paths.Docs.CombineWithFilePath("config.wyam")),
             Settings = new Dictionary<string, object>
             {
                 { "BaseEditUrl", "https://github.com/gittools/GitVersion/tree/main/docs/input/" },
                 { "SourceFiles", context.MakeAbsolute(Paths.Src) + "/**/{!bin,!obj,!packages,!*.Tests,!GitTools.*,}/**/*.cs" },
                 { "Title", "GitVersion" },
-                { "IncludeGlobalNamespace", false }
-            }
+                { "IncludeGlobalNamespace", false },
+                { "IgnoreFolders", "**/mdsource" }
+            },
+            EnvironmentVariables = new Dictionary<string, string>
+            {
+                { "DOTNET_ROLL_FORWARD", "Major" },
+            },
         };
 
         context.StartGroup("Build Setup");

build/docs/Tasks/PublishDocs.cs

@@ -58,7 +58,7 @@ private static bool AnyDocsChanged(ICakeContext context)
         var filesChanged = context.GitDiff(Paths.Root, sourceCommit.Sha);
 
         const string path = "docs/";
-        var docFileChanged = filesChanged.Any(file => file.OldPath.StartsWith(path) || file.Path.StartsWith(path) || file.Path.Contains("config.wyam"));
+        var docFileChanged = filesChanged.Any(file => file.OldPath.StartsWith(path) || file.Path.StartsWith(path));
         return docFileChanged;
     }
 

docs/config.wyam

@@ -38,7 +38,9 @@ tag-prefix: '[abc]'
 
 The built-in configuration for the `GitFlow` workflow (`workflow: GitFlow/v1`) looks like:
 
-```yaml
+<!-- snippet: /docs/workflows/GitFlow/v1.yml -->
+<a id='snippet-/docs/workflows/GitFlow/v1.yml'></a>
+```yml
 assembly-versioning-scheme: MajorMinorPatch
 assembly-file-versioning-scheme: MajorMinorPatch
 tag-prefix: '[vV]?'
@@ -207,10 +209,14 @@ tracks-release-branches: false
 is-release-branch: false
 is-main-branch: false
 ```
+<sup><a href='/docs/workflows/GitFlow/v1.yml#L1-L167' title='Snippet source file'>snippet source</a> | <a href='#snippet-/docs/workflows/GitFlow/v1.yml' title='Start of snippet'>anchor</a></sup>
+<!-- endSnippet -->
 
 The supported built-in configuration for the `GitHubFlow` workflow (`workflow: GitHubFlow/v1`) looks like:
 
-```yaml
+<!-- snippet: /docs/workflows/GitHubFlow/v1.yml -->
+<a id='snippet-/docs/workflows/GitHubFlow/v1.yml'></a>
+```yml
 assembly-versioning-scheme: MajorMinorPatch
 assembly-file-versioning-scheme: MajorMinorPatch
 tag-prefix: '[vV]?'
@@ -270,12 +276,12 @@ branches:
     increment: Inherit
     prevent-increment:
       when-current-commit-tagged: false
+    track-merge-message: true
     regex: ^features?[/-](?<BranchName>.+)
     source-branches:
     - main
     - release
     is-source-branch-for: []
-    track-merge-message: true
     is-main-branch: false
     pre-release-weight: 30000
   pull-request:
@@ -286,28 +292,28 @@ branches:
       of-merged-branch: true
       when-current-commit-tagged: false
     label-number-pattern: '[/-](?<number>\d+)'
+    track-merge-message: true
     regex: ^(pull|pull\-requests|pr)[/-]
     source-branches:
     - main
     - release
     - feature
     is-source-branch-for: []
-    track-merge-message: true
     pre-release-weight: 30000
   unknown:
     mode: ManualDeployment
     label: '{BranchName}'
     increment: Inherit
     prevent-increment:
       when-current-commit-tagged: false
+    track-merge-message: false
     regex: (?<BranchName>.+)
     source-branches:
     - main
     - release
     - feature
     - pull-request
     is-source-branch-for: []
-    track-merge-message: false
     is-main-branch: false
 ignore:
   sha: []
@@ -328,10 +334,14 @@ tracks-release-branches: false
 is-release-branch: false
 is-main-branch: false
 ```
+<sup><a href='/docs/workflows/GitHubFlow/v1.yml#L1-L116' title='Snippet source file'>snippet source</a> | <a href='#snippet-/docs/workflows/GitHubFlow/v1.yml' title='Start of snippet'>anchor</a></sup>
+<!-- endSnippet -->
 
 The preview built-in configuration (experimental usage only) for the `TrunkBased` workflow (`workflow: TrunkBased/preview1`) looks like:
 
-```yaml
+<!-- snippet: /docs/workflows/TrunkBased/preview1.yml -->
+<a id='snippet-/docs/workflows/TrunkBased/preview1.yml'></a>
+```yml
 assembly-versioning-scheme: MajorMinorPatch
 assembly-file-versioning-scheme: MajorMinorPatch
 tag-prefix: '[vV]?'
@@ -346,55 +356,74 @@ merge-message-formats: {}
 update-build-number: true
 semantic-version-format: Strict
 strategies:
-- Mainline
 - ConfiguredNextVersion
+- Mainline
 branches:
   main:
     mode: ContinuousDeployment
     label: ''
     increment: Patch
     prevent-increment:
       of-merged-branch: true
-      when-current-commit-tagged: true
     track-merge-target: false
+    track-merge-message: true
     regex: ^master$|^main$
     source-branches: []
+    is-source-branch-for: []
     tracks-release-branches: false
     is-release-branch: false
     is-main-branch: true
     pre-release-weight: 55000
   feature:
+    mode: ContinuousDelivery
+    label: '{BranchName}'
     increment: Minor
-    regex: ^features?[/-](?<BranchName>.+)
     prevent-increment:
       when-current-commit-tagged: false
+    track-merge-message: true
+    regex: ^features?[/-](?<BranchName>.+)
     source-branches:
     - main
+    is-source-branch-for: []
+    is-main-branch: false
     pre-release-weight: 30000
   hotfix:
+    mode: ContinuousDelivery
+    label: '{BranchName}'
     increment: Patch
-    regex: ^hotfix(es)?[/-](?<BranchName>.+)
     prevent-increment:
       when-current-commit-tagged: false
+    regex: ^hotfix(es)?[/-](?<BranchName>.+)
     source-branches:
     - main
+    is-source-branch-for: []
+    is-release-branch: true
+    is-main-branch: false
     pre-release-weight: 30000
   pull-request:
     mode: ContinuousDelivery
     label: PullRequest
     increment: Inherit
+    prevent-increment:
+      of-merged-branch: true
+      when-current-commit-tagged: false
     label-number-pattern: '[/-](?<number>\d+)'
+    track-merge-message: true
     regex: ^(pull|pull\-requests|pr)[/-]
     source-branches:
     - main
+    - feature
+    - hotfix
+    is-source-branch-for: []
     pre-release-weight: 30000
   unknown:
     increment: Patch
-    regex: (?<BranchName>.+)
     prevent-increment:
       when-current-commit-tagged: false
+    regex: (?<BranchName>.+)
     source-branches:
     - main
+    is-source-branch-for: []
     pre-release-weight: 30000
 ignore:
   sha: []
@@ -409,10 +438,14 @@ track-merge-target: false
 track-merge-message: true
 commit-message-incrementing: Enabled
 regex: ''
+source-branches: []
+is-source-branch-for: []
 tracks-release-branches: false
 is-release-branch: false
 is-main-branch: false
 ```
+<sup><a href='/docs/workflows/TrunkBased/preview1.yml#L1-L101' title='Snippet source file'>snippet source</a> | <a href='#snippet-/docs/workflows/TrunkBased/preview1.yml' title='Start of snippet'>anchor</a></sup>
+<!-- endSnippet -->
 
 The details of the available options are as follows: