Release v7: complete Z21 LAN protocol, docs, CI/CD, and tooling

.github/workflows/Build.yml

@@ -1,4 +1,5 @@
-# This workflow will build a .NET project
+# Continuous integration: build and test on every push and pull request.
+# Publishing to NuGet is handled separately by Release.yml (tag-gated).
 # For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-net
 
 name: Build
@@ -16,69 +17,18 @@ jobs:
     - name: Checkout code
       uses: actions/checkout@v4
       with:
-        fetch-depth: 0  # Required for GitVersion to access full commit history
+        fetch-depth: 0  # Nerdbank.GitVersioning needs full history to compute the version
 
     - name: Setup .NET
       uses: actions/setup-dotnet@v4
       with:
         dotnet-version: 8.0.x
 
-    - name: Setup GitVersion
-      uses: GitTools/actions/gitversion/setup@v0.9.10
-      with:
-        versionSpec: '5.x'
-
-    - name: Run GitVersion
-      id: gitversion
-      uses: GitTools/actions/gitversion/execute@v0.9.10
-
     - name: Restore dependencies
       run: dotnet restore src/Z21.sln
-
-    - name: Build for testing (Debug)
-      run: dotnet build src/Z21.sln --no-restore /p:Version=${{ steps.gitversion.outputs.semVer }}
-
-    - name: Test
-      run: dotnet test src/Z21.sln --no-build --verbosity normal
 
-    - name: Build for packaging (Release)
-      run: dotnet build src/Z21.sln --no-restore --configuration Release /p:Version=${{ steps.gitversion.outputs.semVer }}
-
-    - name: Tag commit with GitVersion
-      if: github.event_name == 'push'
-      run: |
-        git config user.name "github-actions[bot]"
-        git config user.email "github-actions[bot]@users.noreply.github.com"
-        git tag v${{ steps.gitversion.outputs.semVer }}
-        git push origin v${{ steps.gitversion.outputs.semVer }}
-
-    - name: Pack Z21.sln NuGet package
-      run: |
-        dotnet pack src/Z21.sln --no-build --configuration Release \
-          /p:PackageVersion=${{ steps.gitversion.outputs.semVer }} \
-          /p:Version=${{ steps.gitversion.outputs.semVer }} \
-          --output ./nupkgs
+    - name: Build (Release)
+      run: dotnet build src/Z21.sln --no-restore --configuration Release
 
-    - name: Pack Z21.DependencyInjection NuGet package
-      run: |
-        dotnet pack src/Z21.DependencyInjection/Z21.DependencyInjection.csproj --no-build --configuration Release \
-          /p:PackageVersion=${{ steps.gitversion.outputs.semVer }} \
-          /p:Version=${{ steps.gitversion.outputs.semVer }} \
-          --output ./nupkgs
-
-    - name: Pack Z21.Autofac NuGet package
-      run: |
-        dotnet pack src/Z21.Autofac/Z21.Autofac.csproj --no-build --configuration Release \
-          /p:PackageVersion=${{ steps.gitversion.outputs.semVer }} \
-          /p:Version=${{ steps.gitversion.outputs.semVer }} \
-          --output ./nupkgs
-
-    - name: Push packages to NuGet
-      if: |
-        github.ref == 'refs/heads/main'
-      run: |
-        for pkg in ./nupkgs/*.nupkg; do
-          dotnet nuget push "$pkg" \
-            --api-key ${{ secrets.NUGET_API_KEY }} \
-            --source https://api.nuget.org/v3/index.json
-        done
+    - name: Test
+      run: dotnet test src/Z21.sln --no-build --configuration Release --verbosity normal

.github/workflows/BuildAndDeployDoc.yml

@@ -1,37 +1,67 @@
 name: Github Pages
 
+# Builds the API documentation with DocFX (generated from the source XML doc comments)
+# and publishes it with GitHub's native Pages deployment. Nothing is committed to the
+# repository. Requires Settings -> Pages -> Source = "GitHub Actions".
 on:
   push:
     branches: [ "main" ]
+    paths:
+      - 'docfx/**'
+      - 'src/**'
+      - '.github/workflows/BuildAndDeployDoc.yml'
   pull_request:
     branches: [ "main" ]
+    paths:
+      - 'docfx/**'
+      - 'src/**'
+      - '.github/workflows/BuildAndDeployDoc.yml'
   workflow_dispatch:
 
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow one concurrent deployment; let an in-progress run finish rather than cancel it.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
 jobs:
   build:
     runs-on: ubuntu-latest
-
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
-
-      - name: Copy README as index.md
-        run: cp README.md src/index.md
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # DocFX builds the projects; Nerdbank.GitVersioning needs full history
 
       - name: Setup .NET
-        uses: actions/setup-dotnet@v3
+        uses: actions/setup-dotnet@v4
         with:
-          dotnet-version: '8.x'
+          dotnet-version: 8.0.x
 
       - name: Install DocFX
         run: dotnet tool install -g docfx
 
-      - name: Build Docs
-        run: docfx src/docfx.json
+      - name: Build docs (docfx -> docfx/_site)
+        run: docfx docfx/docfx.json
 
-      - name: Deploy to GitHub Pages
-        uses: peaceiris/actions-gh-pages@v3
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
         with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./src/_site
-          destination_dir: .
+          path: docfx/_site
+
+  deploy:
+    # PRs only build (to validate); deployment happens on main / manual dispatch.
+    if: github.event_name != 'pull_request'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/MutationTesting.yml

@@ -15,10 +15,12 @@ jobs:
 
     steps:
     - name: Checkout code
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
+      with:
+        fetch-depth: 0  # Nerdbank.GitVersioning needs full history to compute the version
 
     - name: Setup .NET
-      uses: actions/setup-dotnet@v3
+      uses: actions/setup-dotnet@v4
       with:
         dotnet-version: '8.0.x'
 

.github/workflows/Release.yml

@@ -0,0 +1,57 @@
+# Continuous delivery: pack and publish the NuGet packages on every merge to main.
+#
+# Versions are produced automatically by Nerdbank.GitVersioning (version.json + git
+# height), so they increment on every commit — no tags or manual version bumps. A push
+# to main (which is what merging a pull request produces) builds, tests, packs the whole
+# solution once, and pushes all packages to NuGet.org with --skip-duplicate.
+
+name: Release
+
+on:
+  push:
+    branches: [ main ]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release-main
+  cancel-in-progress: false
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Nerdbank.GitVersioning needs full history to compute the version
+
+      - name: Setup .NET
+        uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: 8.0.x
+
+      - name: Restore dependencies
+        run: dotnet restore src/Z21.sln
+
+      - name: Build (Release)
+        run: dotnet build src/Z21.sln --no-restore --configuration Release
+
+      - name: Test
+        run: dotnet test src/Z21.sln --no-build --configuration Release --verbosity normal
+
+      - name: Pack
+        run: dotnet pack src/Z21.sln --no-build --configuration Release --output ./nupkgs
+
+      - name: Upload packages artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: nupkgs
+          path: ./nupkgs/*.nupkg
+
+      - name: Push to NuGet
+        if: github.ref == 'refs/heads/main'   # never publish from a manually-dispatched non-main branch
+        run: dotnet nuget push "./nupkgs/*.nupkg" --api-key ${{ secrets.NUGET_API_KEY }} --source https://api.nuget.org/v3/index.json --skip-duplicate

.gitignore

@@ -396,4 +396,9 @@ _UpgradeReport_Files/
 
 Thumbs.db
 Desktop.ini
-.DS_Store
+.DS_Store
+
+# DocFX generated output (the site is published by CI via GitHub Pages, never committed)
+docfx/_site/
+docfx/api/
+**/*.manifest