diff --git a/.config/dotnet-tools.json b/.config/dotnet-tools.json index 384249f..e417228 100644 --- a/.config/dotnet-tools.json +++ b/.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" + ] } } } \ No newline at end of file diff --git a/.cspell.json b/.cspell.json index e063685..af3642f 100644 --- a/.cspell.json +++ b/.cspell.json @@ -84,6 +84,8 @@ "trx", "vbproj", "vcxproj", + "versionmark", + "VersionMark", "Weasyprint", "wildcards", "YamlDotNet", diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml index e066616..103ade7 100644 --- a/.github/workflows/build.yaml +++ b/.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 diff --git a/.versionmark.yaml b/.versionmark.yaml new file mode 100644 index 0000000..aac6ce7 --- /dev/null +++ b/.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: '(?\d+\.\d+\.\d+(?:\.\d+)?)' + + # Git + git: + command: git --version + regex: '(?i)git version (?\d+\.\d+\.\d+)' + + # Node.js + node: + command: node --version + regex: '(?i)v(?\d+\.\d+\.\d+)' + + # npm + npm: + command: npm --version + regex: '(?\d+\.\d+\.\d+)' + + # SonarScanner for .NET (from dotnet tool list) + dotnet-sonarscanner: + command: dotnet tool list + regex: '(?i)dotnet-sonarscanner\s+(?\d+\.\d+\.\d+)' + + # Pandoc (DemaConsulting.PandocTool from dotnet tool list) + pandoc: + command: dotnet tool list + regex: '(?i)demaconsulting\.pandoctool\s+(?\d+\.\d+\.\d+)' + + # WeasyPrint (DemaConsulting.WeasyPrintTool from dotnet tool list) + weasyprint: + command: dotnet tool list + regex: '(?i)demaconsulting\.weasyprinttool\s+(?\d+\.\d+\.\d+)' + + # SarifMark (DemaConsulting.SarifMark from dotnet tool list) + sarifmark: + command: dotnet tool list + regex: '(?i)demaconsulting\.sarifmark\s+(?\d+\.\d+\.\d+)' + + # SonarMark (DemaConsulting.SonarMark from dotnet tool list) + sonarmark: + command: dotnet tool list + regex: '(?i)demaconsulting\.sonarmark\s+(?\d+\.\d+\.\d+)' + + # BuildMark (DemaConsulting.BuildMark from dotnet tool list) + buildmark: + command: dotnet tool list + regex: '(?i)demaconsulting\.buildmark\s+(?\d+\.\d+\.\d+)' + + # VersionMark (DemaConsulting.VersionMark from dotnet tool list) + versionmark: + command: dotnet tool list + regex: '(?i)demaconsulting\.versionmark\s+(?\d+\.\d+\.\d+)' diff --git a/docs/buildnotes/definition.yaml b/docs/buildnotes/definition.yaml new file mode 100644 index 0000000..62699f2 --- /dev/null +++ b/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 diff --git a/docs/buildnotes/introduction.md b/docs/buildnotes/introduction.md new file mode 100644 index 0000000..14b7cd0 --- /dev/null +++ b/docs/buildnotes/introduction.md @@ -0,0 +1,33 @@ +# Introduction + +This document contains the build notes for the SpdxTool project. + +## Purpose + +This report serves as a comprehensive record of changes and bug fixes for this +release of SpdxTool. It provides transparency about what has changed since the +previous version and helps users understand the improvements and fixes included +in this build. + +## Scope + +This build notes report covers: + +- Version information and commit details +- Changes and new features implemented +- Bugs fixed in this release + +## Generation Source + +This report is automatically generated by the BuildMark tool, analyzing the +Git repository history and issue tracking information. It serves as evidence of +changes and improvements included in this release. + +## Audience + +This document is intended for: + +- Software developers working on SpdxTool +- Users evaluating what has changed in this release +- Project stakeholders tracking progress +- Contributors understanding recent changes diff --git a/docs/buildnotes/title.txt b/docs/buildnotes/title.txt new file mode 100644 index 0000000..0ac212d --- /dev/null +++ b/docs/buildnotes/title.txt @@ -0,0 +1,17 @@ +--- +title: SpdxTool +subtitle: Build Notes +author: DEMA Consulting +description: Build notes for the SpdxTool C# library for manipulating SPDX SBOM files +lang: en-US +keywords: + - SpdxTool + - Build Notes + - Release Notes + - C# + - .NET + - SPDX + - SBOM + - Software Bill of Materials + - Documentation +---