fix: align build pipeline with TemplateDotNetTool patterns

.config/dotnet-tools.json

@@ -37,6 +37,18 @@
       "commands": [
         "sarifmark"
       ]
+    },
+    "demaconsulting.buildmark": {
+      "version": "0.3.0",
+      "commands": [
+        "buildmark"
+      ]
+    },
+    "demaconsulting.versionmark": {
+      "version": "0.1.0",
+      "commands": [
+        "versionmark"
+      ]
     }
   }
 }

.cspell.json

@@ -84,6 +84,8 @@
     "trx",
     "vbproj",
     "vcxproj",
+    "versionmark",
+    "VersionMark",
     "Weasyprint",
     "wildcards",
     "YamlDotNet",

.github/workflows/build.yaml

@@ -13,6 +13,8 @@ on:
 
 
 jobs:
+  # Performs quick quality checks for project formatting consistency including
+  # markdown linting, spell checking, and YAML validation.
   quality-checks:
     name: Quality Checks
     runs-on: ubuntu-latest
@@ -22,6 +24,28 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v6
 
+      - name: Setup dotnet
+        uses: actions/setup-dotnet@v5
+        with:
+          dotnet-version: 10.x
+
+      - name: Restore Tools
+        run: >
+          dotnet tool restore
+
+      - name: Capture tool versions
+        shell: bash
+        run: |
+          echo "Capturing tool versions..."
+          dotnet versionmark --capture --job-id "quality" -- dotnet git versionmark
+          echo "✓ Tool versions captured"
+
+      - name: Upload version capture
+        uses: actions/upload-artifact@v6
+        with:
+          name: version-capture-quality
+          path: versionmark-quality.json
+
       - name: Spell Check
         uses: streetsidesoftware/cspell-action@v8
         with:
@@ -44,6 +68,9 @@ jobs:
         with:
           config_file: .yamllint.yaml
 
+  # Builds and unit-tests the project on supported operating systems to ensure
+  # unit-tests operate on all platforms and to run SonarScanner for generating
+  # the code quality report.
   build:
     # Permissions for this job
     permissions:
@@ -154,6 +181,23 @@ jobs:
           --no-restore
           --property:PackageVersion=${{ inputs.version }}
 
+      - name: Capture tool versions
+        shell: bash
+        run: |
+          echo "Capturing tool versions..."
+          # Create short job ID: build-win, build-ubuntu
+          OS_SHORT=$(echo "${{ matrix.os }}" | sed 's/windows-latest/win/;s/ubuntu-latest/ubuntu/')
+          JOB_ID="build-${OS_SHORT}"
+          dotnet versionmark --capture --job-id "${JOB_ID}" -- \
+            dotnet git dotnet-sonarscanner versionmark
+          echo "✓ Tool versions captured"
+
+      - name: Upload version capture
+        uses: actions/upload-artifact@v6
+        with:
+          name: version-capture-${{ matrix.os }}
+          path: versionmark-build-*.json
+
       - name: Self Validate
         run: >
           dotnet
@@ -173,6 +217,8 @@ jobs:
             *summary.md
             validate.log
 
+  # Runs CodeQL security and quality analysis, gathering results to include
+  # in the code quality report.
   codeql:
     name: CodeQL Analysis
     needs: quality-checks
@@ -230,6 +276,8 @@ jobs:
           name: codeql-sarif
           path: sarif-results/csharp.sarif
 
+  # Builds the supporting documentation including user guides, code quality
+  # reports, and build notes.
   build-docs:
     name: Build Documents
     runs-on: windows-latest
@@ -240,45 +288,63 @@ jobs:
       contents: read
 
     steps:
+      # === CHECKOUT AND DOWNLOAD ARTIFACTS ===
+      # This section retrieves the code and all necessary artifacts from previous jobs.
+      # Downstream projects: Add any additional artifact downloads here.
+
       - name: Checkout
         uses: actions/checkout@v6
 
-      - name: Setup dotnet
-        uses: actions/setup-dotnet@v5
+      - name: Download CodeQL SARIF
+        uses: actions/download-artifact@v7
         with:
-          dotnet-version: '10.x'
+          name: codeql-sarif
+          path: codeql-results
 
-      - name: Restore Tools
-        run: >
-          dotnet tool restore
+      - name: Download all version captures
+        uses: actions/download-artifact@v7
+        with:
+          path: version-captures
+          pattern: 'version-capture-*'
+        continue-on-error: true
+
+      # === INSTALL DEPENDENCIES ===
+      # This section installs all required dependencies and tools for document generation.
+      # Downstream projects: Add any additional dependency installations here.
 
       - name: Setup Node.js
         uses: actions/setup-node@v6
         with:
           node-version: 'lts/*'
 
+      - name: Setup dotnet
+        uses: actions/setup-dotnet@v5
+        with:
+          dotnet-version: '10.x'
+
       - name: Install npm dependencies
         run: >
           npm install
 
-      - name: Build PDF with Pandoc
+      - name: Restore Tools
         run: >
-          dotnet pandoc
-          --defaults docs/guide/definition.yaml
-          --filter node_modules/.bin/mermaid-filter.cmd
-          --output docs/guide/guide.html
+          dotnet tool restore
 
-      - name: Convert HTML to PDF with Weasyprint
-        run: >
-          dotnet weasyprint
-          docs/guide/guide.html
-          "docs/SpdxTool User Guide.pdf"
+      # === CAPTURE TOOL VERSIONS ===
+      # This section captures the versions of all tools used in the build process.
+      # Downstream projects: Add any additional tools to capture here.
 
-      - name: Download CodeQL SARIF
-        uses: actions/download-artifact@v7
-        with:
-          name: codeql-sarif
-          path: codeql-results
+      - name: Capture tool versions for build-docs
+        shell: bash
+        run: |
+          echo "Capturing tool versions..."
+          dotnet versionmark --capture --job-id "build-docs" -- \
+            dotnet git node npm pandoc weasyprint sarifmark sonarmark buildmark versionmark
+          echo "✓ Tool versions captured"
+
+      # === GENERATE MARKDOWN REPORTS ===
+      # This section generates all markdown reports from various tools and sources.
+      # Downstream projects: Add any additional markdown report generation steps here.
 
       - name: Generate CodeQL Quality Report with SarifMark
         run: >
@@ -312,6 +378,60 @@ jobs:
           echo "=== SonarCloud Quality Report ==="
           cat docs/quality/sonar-quality.md
 
+      - name: Generate Build Notes with BuildMark
+        shell: bash
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: >
+          dotnet buildmark
+          --build-version ${{ inputs.version }}
+          --report docs/buildnotes.md
+          --report-depth 1
+
+      - name: Display Build Notes Report
+        shell: bash
+        run: |
+          echo "=== Build Notes Report ==="
+          cat docs/buildnotes.md
+
+      - name: Publish Tool Versions
+        shell: bash
+        run: |
+          echo "Publishing tool versions..."
+          dotnet versionmark --publish --report docs/buildnotes/versions.md --report-depth 1 \
+            -- "versionmark-*.json" "version-captures/**/versionmark-*.json"
+          echo "✓ Tool versions published"
+
+      - name: Display Tool Versions Report
+        shell: bash
+        run: |
+          echo "=== Tool Versions Report ==="
+          cat docs/buildnotes/versions.md
+
+      # === GENERATE HTML DOCUMENTS WITH PANDOC ===
+      # This section converts markdown documents to HTML using Pandoc.
+      # Downstream projects: Add any additional Pandoc HTML generation steps here.
+
+      - name: Generate Build Notes HTML with Pandoc
+        shell: bash
+        run: >
+          dotnet pandoc
+          --defaults docs/buildnotes/definition.yaml
+          --filter node_modules/.bin/mermaid-filter.cmd
+          --metadata version="${{ inputs.version }}"
+          --metadata date="$(date +'%Y-%m-%d')"
+          --output docs/buildnotes/buildnotes.html
+
+      - name: Generate Guide HTML with Pandoc
+        shell: bash
+        run: >
+          dotnet pandoc
+          --defaults docs/guide/definition.yaml
+          --filter node_modules/.bin/mermaid-filter.cmd
+          --metadata version="${{ inputs.version }}"
+          --metadata date="$(date +'%Y-%m-%d')"
+          --output docs/guide/guide.html
+
       - name: Generate Code Quality HTML with Pandoc
         shell: bash
         run: >
@@ -322,14 +442,36 @@ jobs:
           --metadata date="$(date +'%Y-%m-%d')"
           --output docs/quality/quality.html
 
+      # === GENERATE PDF DOCUMENTS WITH WEASYPRINT ===
+      # This section converts HTML documents to PDF using Weasyprint.
+      # Downstream projects: Add any additional Weasyprint PDF generation steps here.
+
+      - name: Generate Build Notes PDF with Weasyprint
+        run: >
+          dotnet weasyprint
+          docs/buildnotes/buildnotes.html
+          "docs/SpdxTool Build Notes.pdf"
+
+      - name: Generate Guide PDF with Weasyprint
+        run: >
+          dotnet weasyprint
+          docs/guide/guide.html
+          "docs/SpdxTool User Guide.pdf"
+
       - name: Generate Code Quality PDF with Weasyprint
         run: >
           dotnet weasyprint
           docs/quality/quality.html
           "docs/SpdxTool Code Quality.pdf"
 
+      # === UPLOAD ARTIFACTS ===
+      # This section uploads all generated documentation artifacts.
+      # Downstream projects: Add any additional artifact uploads here.
+
       - name: Upload Document Artifacts
         uses: actions/upload-artifact@v6
         with:
           name: documents
-          path: docs/*.pdf
+          path: |
+            docs/*.pdf
+            docs/buildnotes.md

.versionmark.yaml

@@ -0,0 +1,59 @@
+---
+# VersionMark Configuration File
+# This file defines which tools to capture and how to extract their version information.
+
+tools:
+  # .NET SDK
+  dotnet:
+    command: dotnet --version
+    regex: '(?<version>\d+\.\d+\.\d+(?:\.\d+)?)'
+
+  # Git
+  git:
+    command: git --version
+    regex: '(?i)git version (?<version>\d+\.\d+\.\d+)'
+
+  # Node.js
+  node:
+    command: node --version
+    regex: '(?i)v(?<version>\d+\.\d+\.\d+)'
+
+  # npm
+  npm:
+    command: npm --version
+    regex: '(?<version>\d+\.\d+\.\d+)'
+
+  # SonarScanner for .NET (from dotnet tool list)
+  dotnet-sonarscanner:
+    command: dotnet tool list
+    regex: '(?i)dotnet-sonarscanner\s+(?<version>\d+\.\d+\.\d+)'
+
+  # Pandoc (DemaConsulting.PandocTool from dotnet tool list)
+  pandoc:
+    command: dotnet tool list
+    regex: '(?i)demaconsulting\.pandoctool\s+(?<version>\d+\.\d+\.\d+)'
+
+  # WeasyPrint (DemaConsulting.WeasyPrintTool from dotnet tool list)
+  weasyprint:
+    command: dotnet tool list
+    regex: '(?i)demaconsulting\.weasyprinttool\s+(?<version>\d+\.\d+\.\d+)'
+
+  # SarifMark (DemaConsulting.SarifMark from dotnet tool list)
+  sarifmark:
+    command: dotnet tool list
+    regex: '(?i)demaconsulting\.sarifmark\s+(?<version>\d+\.\d+\.\d+)'
+
+  # SonarMark (DemaConsulting.SonarMark from dotnet tool list)
+  sonarmark:
+    command: dotnet tool list
+    regex: '(?i)demaconsulting\.sonarmark\s+(?<version>\d+\.\d+\.\d+)'
+
+  # BuildMark (DemaConsulting.BuildMark from dotnet tool list)
+  buildmark:
+    command: dotnet tool list
+    regex: '(?i)demaconsulting\.buildmark\s+(?<version>\d+\.\d+\.\d+)'
+
+  # VersionMark (DemaConsulting.VersionMark from dotnet tool list)
+  versionmark:
+    command: dotnet tool list
+    regex: '(?i)demaconsulting\.versionmark\s+(?<version>\d+\.\d+\.\d+)'

docs/buildnotes/definition.yaml

@@ -0,0 +1,12 @@
+---
+resource-path:
+  - docs/buildnotes
+  - docs/template
+input-files:
+  - docs/buildnotes/title.txt
+  - docs/buildnotes/introduction.md
+  - docs/buildnotes.md
+  - docs/buildnotes/versions.md
+template: template.html
+table-of-contents: true
+number-sections: true