Implement build-time version replacement for documentation

.github/workflows/ci.yml

@@ -166,6 +166,11 @@ jobs:
           echo "ASSEMBLY_VERSION=${{ steps.gitversion.outputs.assemblySemVer }}" >> $GITHUB_ENV
           echo "FILE_VERSION=${{ steps.gitversion.outputs.assemblySemFileVer }}" >> $GITHUB_ENV
 
+      - name: Replace version placeholders in documentation
+        shell: pwsh
+        run: |
+          ./build/replace-version.ps1 -Version "${{ env.PACKAGE_VERSION }}" -Path "."
+
       - name: Build (Release)
         run: >
           dotnet build JD.Efcpt.Build.sln

CONTRIBUTING.md

@@ -374,6 +374,50 @@ When contributing, please update:
 - **XML comments** - For all public APIs
 - **Code comments** - For complex logic
 
+#### Version Placeholders in Documentation
+
+Documentation and README files use `PACKAGE_VERSION` as a placeholder for version numbers. This placeholder is automatically replaced with the actual version during the CI/CD build process.
+
+**When to use placeholders:**
+
+Use `PACKAGE_VERSION` in documentation for:
+- SDK version references: `Sdk="JD.Efcpt.Sdk/PACKAGE_VERSION"`
+- PackageReference version attributes: `Version="PACKAGE_VERSION"`
+- Any mention of the current package version in examples
+
+**Example:**
+
+```xml
+<!-- In documentation, write: -->
+<Project Sdk="JD.Efcpt.Sdk/PACKAGE_VERSION">
+  <ItemGroup>
+    <PackageReference Include="JD.Efcpt.Build" Version="PACKAGE_VERSION" />
+  </ItemGroup>
+</Project>
+
+<!-- During CI build, this becomes (e.g., for version 1.2.3): -->
+<Project Sdk="JD.Efcpt.Sdk/1.2.3">
+  <ItemGroup>
+    <PackageReference Include="JD.Efcpt.Build" Version="1.2.3" />
+  </ItemGroup>
+</Project>
+```
+
+**Testing version replacement locally:**
+
+```bash
+# Dry run (shows what would be replaced)
+pwsh ./build/replace-version.ps1 -Version "1.2.3" -DryRun
+
+# Actually replace versions
+pwsh ./build/replace-version.ps1 -Version "1.2.3"
+
+# Revert changes after testing
+git checkout README.md docs/ samples/
+```
+
+**Important:** Always commit documentation with `PACKAGE_VERSION` placeholders, not actual version numbers. The CI/CD workflow automatically replaces these during the build and package process.
+
 ### Commit Messages
 
 Follow conventional commits format:

README.md

@@ -23,7 +23,7 @@ dotnet build
 ### Option B: SDK Approach (Recommended)
 
 ```xml
-<Project Sdk="JD.Efcpt.Sdk/1.0.0">
+<Project Sdk="JD.Efcpt.Sdk/PACKAGE_VERSION">
     <PropertyGroup>
         <TargetFramework>net8.0</TargetFramework>
     </PropertyGroup>
@@ -101,7 +101,7 @@ Automatically generate SQL scripts from your live database when JD.Efcpt.Build d
         <EfcptConnectionString>Server=...;Database=MyDb;...</EfcptConnectionString>
     </PropertyGroup>
     <ItemGroup>
-        <PackageReference Include="JD.Efcpt.Build" Version="*" />
+        <PackageReference Include="JD.Efcpt.Build" Version="PACKAGE_VERSION" />
     </ItemGroup>
 </Project>
 ```
@@ -110,7 +110,7 @@ Automatically generate SQL scripts from your live database when JD.Efcpt.Build d
 ```xml
 <ItemGroup>
     <ProjectReference Include="..\DatabaseProject\DatabaseProject.csproj" />
-    <PackageReference Include="JD.Efcpt.Build" Version="*" />
+    <PackageReference Include="JD.Efcpt.Build" Version="PACKAGE_VERSION" />
 </ItemGroup>
 ```
 

build/README.md

@@ -0,0 +1,94 @@
+# Build Scripts
+
+This directory contains build-time scripts and tools used during the CI/CD process.
+
+## replace-version.ps1
+
+PowerShell script that replaces version placeholders in documentation files with actual version numbers from GitVersion.
+
+### Purpose
+
+Ensures that all documentation (README, docs, samples) shows the current package version without requiring manual updates. This prevents version drift and user confusion.
+
+### Usage
+
+```powershell
+# Dry run - shows what would be replaced without making changes
+./replace-version.ps1 -Version "1.2.3" -DryRun
+
+# Replace versions in current directory
+./replace-version.ps1 -Version "1.2.3"
+
+# Replace versions in specific path
+./replace-version.ps1 -Version "1.2.3" -Path "../docs"
+```
+
+### Parameters
+
+- **Version** (required): The version string to use for replacement (e.g., "1.2.3")
+- **Path** (optional): The root path to search for files (defaults to current directory)
+- **DryRun** (optional): If specified, shows what would be replaced without making changes
+
+### Placeholders
+
+The script recognizes and replaces the following patterns:
+
+1. **SDK version in Sdk attribute**: `Sdk="JD.Efcpt.Sdk/PACKAGE_VERSION"`
+2. **PackageReference Version attribute**: `Version="PACKAGE_VERSION"`
+3. **Inline text placeholder**: `PACKAGE_VERSION` (word boundary)
+
+### CI/CD Integration
+
+This script is automatically executed during the release build in the CI/CD workflow:
+
+1. GitVersion calculates the version based on commits and tags
+2. The version is stored in `PACKAGE_VERSION` environment variable
+3. `replace-version.ps1` is executed to update all documentation
+4. The build continues with the updated documentation
+5. NuGet packages are created with the correct version in all docs
+
+### Testing
+
+```bash
+# Test in dry run mode
+pwsh ./build/replace-version.ps1 -Version "1.2.3" -DryRun
+
+# Test actual replacement (remember to revert after)
+pwsh ./build/replace-version.ps1 -Version "1.2.3"
+
+# Revert test changes
+git checkout README.md docs/ samples/
+```
+
+### Adding Version Placeholders
+
+When adding new documentation:
+
+1. Use `PACKAGE_VERSION` instead of hardcoded version numbers
+2. Place the placeholder where users would see version numbers
+3. Test with the script to ensure replacement works correctly
+
+**Example:**
+
+```xml
+<!-- Good - uses placeholder -->
+<Project Sdk="JD.Efcpt.Sdk/PACKAGE_VERSION">
+  <ItemGroup>
+    <PackageReference Include="JD.Efcpt.Build" Version="PACKAGE_VERSION" />
+  </ItemGroup>
+</Project>
+
+<!-- Bad - hardcoded version -->
+<Project Sdk="JD.Efcpt.Sdk/1.0.0">
+  <ItemGroup>
+    <PackageReference Include="JD.Efcpt.Build" Version="1.0.0" />
+  </ItemGroup>
+</Project>
+```
+
+### Notes
+
+- The script only processes markdown (.md) files
+- Files in `.git` and `node_modules` directories are excluded
+- All replacements use regex for precise pattern matching
+- The script preserves file encoding and line endings

build/replace-version.ps1

@@ -0,0 +1,112 @@
+#!/usr/bin/env pwsh
+<#
+.SYNOPSIS
+    Replaces version placeholders in documentation files.
+
+.DESCRIPTION
+    This script replaces PACKAGE_VERSION placeholders in markdown and documentation
+    files with the actual version number from GitVersion or provided as a parameter.
+
+.PARAMETER Version
+    The version string to use for replacement (e.g., "1.2.3")
+
+.PARAMETER Path
+    The root path to search for files (defaults to repository root)
+
+.PARAMETER DryRun
+    If specified, shows what would be replaced without making changes
+
+.EXAMPLE
+    ./replace-version.ps1 -Version "1.2.3"
+
+.EXAMPLE
+    ./replace-version.ps1 -Version "1.2.3" -Path "../docs" -DryRun
+#>
+
+param(
+    [Parameter(Mandatory=$true)]
+    [string]$Version,
+
+    [Parameter(Mandatory=$false)]
+    [string]$Path = ".",
+
+    [Parameter(Mandatory=$false)]
+    [switch]$DryRun
+)
+
+$ErrorActionPreference = "Stop"
+
+# Resolve the path to an absolute path for consistent handling
+$Path = [System.IO.Path]::GetFullPath($Path)
+
+Write-Host "Version Replacement Script" -ForegroundColor Cyan
+Write-Host "=========================" -ForegroundColor Cyan
+Write-Host "Version: $Version" -ForegroundColor Green
+Write-Host "Path: $Path" -ForegroundColor Green
+Write-Host "Dry Run: $DryRun" -ForegroundColor Green
+Write-Host ""
+
+# Define the patterns to replace
+$patterns = @(
+    # SDK version in Sdk attribute
+    @{
+        Pattern = 'Sdk="JD\.Efcpt\.Sdk/PACKAGE_VERSION"'
+        Replacement = "Sdk=`"JD.Efcpt.Sdk/$Version`""
+    },
+    # PackageReference Version attribute
+    @{
+        Pattern = 'Version="PACKAGE_VERSION"'
+        Replacement = "Version=`"$Version`""
+    },
+    # Inline text placeholder
+    @{
+        Pattern = '\bPACKAGE_VERSION\b'
+        Replacement = $Version
+    }
+)
+
+# Find all markdown files
+$files = Get-ChildItem -Path $Path -Recurse -Include "*.md" -File | 
+    Where-Object { $_.FullName -notmatch "[\\/]\.git[\\/]" -and $_.FullName -notmatch "[\\/]node_modules[\\/]" }
+
+Write-Host "Found $($files.Count) markdown files to process" -ForegroundColor Yellow
+Write-Host ""
+
+$totalReplacements = 0
+
+foreach ($file in $files) {
+    # Use GetRelativePath for robust path handling
+    $relativePath = [System.IO.Path]::GetRelativePath($Path, $file.FullName)
+    $content = Get-Content -Path $file.FullName -Raw -ErrorAction Stop
+    $fileReplacements = 0
+
+    foreach ($patternInfo in $patterns) {
+        $matches = [regex]::Matches($content, $patternInfo.Pattern)
+        if ($matches.Count -gt 0) {
+            $content = [regex]::Replace($content, $patternInfo.Pattern, $patternInfo.Replacement)
+            $fileReplacements += $matches.Count
+        }
+    }
+
+    if ($fileReplacements -gt 0) {
+        Write-Host "  $relativePath" -ForegroundColor White
+        Write-Host "    -> $fileReplacements replacement(s)" -ForegroundColor Gray
+
+        if (-not $DryRun) {
+            # Preserve the original file's newline behavior
+            # Get-Content with -Raw preserves trailing newlines, so we use -NoNewline to avoid adding an extra one
+            Set-Content -Path $file.FullName -Value $content -NoNewline -ErrorAction Stop
+        }
+
+        $totalReplacements += $fileReplacements
+    }
+}
+
+Write-Host ""
+if ($DryRun) {
+    Write-Host "Dry run complete. Would have made $totalReplacements replacement(s) across $($files.Count) files." -ForegroundColor Yellow
+} else {
+    Write-Host "Successfully replaced $totalReplacements version placeholder(s)." -ForegroundColor Green
+}
+
+exit 0

docs/index.md

@@ -31,7 +31,7 @@ dotnet build
 ### Option B: SDK Approach (Recommended)
 
 ```xml
-<Project Sdk="JD.Efcpt.Sdk/1.0.0">
+<Project Sdk="JD.Efcpt.Sdk/PACKAGE_VERSION">
     <PropertyGroup>
         <TargetFramework>net8.0</TargetFramework>
     </PropertyGroup>

docs/user-guide/advanced.md

@@ -26,7 +26,7 @@ Create a `Directory.Build.props` file at the solution root:
   </PropertyGroup>
 
   <ItemGroup>
-    <PackageReference Include="JD.Efcpt.Build" Version="x.x.x" />
+    <PackageReference Include="JD.Efcpt.Build" Version="PACKAGE_VERSION" />
   </ItemGroup>
 </Project>
 ```

docs/user-guide/configuration.md

@@ -449,7 +449,7 @@ Just add the package; everything is auto-discovered:
 
 ```xml
 <ItemGroup>
-  <PackageReference Include="JD.Efcpt.Build" Version="x.x.x" />
+  <PackageReference Include="JD.Efcpt.Build" Version="PACKAGE_VERSION" />
 </ItemGroup>
 ```
 
@@ -511,7 +511,7 @@ Include only specific tables:
   </PropertyGroup>
 
   <ItemGroup>
-    <PackageReference Include="JD.Efcpt.Build" Version="x.x.x" />
+    <PackageReference Include="JD.Efcpt.Build" Version="PACKAGE_VERSION" />
   </ItemGroup>
 </Project>
 ```

docs/user-guide/connection-string-mode.md

@@ -320,7 +320,7 @@ Use Windows/Integrated Authentication when possible:
 ```xml
 <Project Sdk="Microsoft.NET.Sdk">
   <ItemGroup>
-    <PackageReference Include="JD.Efcpt.Build" Version="x.x.x" />
+    <PackageReference Include="JD.Efcpt.Build" Version="PACKAGE_VERSION" />
   </ItemGroup>
 
   <PropertyGroup>
@@ -333,7 +333,7 @@ Use Windows/Integrated Authentication when possible:
 ```xml
 <Project Sdk="Microsoft.NET.Sdk">
   <ItemGroup>
-    <PackageReference Include="JD.Efcpt.Build" Version="x.x.x" />
+    <PackageReference Include="JD.Efcpt.Build" Version="PACKAGE_VERSION" />
   </ItemGroup>
 
   <PropertyGroup>
@@ -346,7 +346,7 @@ Use Windows/Integrated Authentication when possible:
 ```xml
 <Project Sdk="Microsoft.NET.Sdk">
   <ItemGroup>
-    <PackageReference Include="JD.Efcpt.Build" Version="x.x.x" />
+    <PackageReference Include="JD.Efcpt.Build" Version="PACKAGE_VERSION" />
   </ItemGroup>
 
   <PropertyGroup>
@@ -359,7 +359,7 @@ Use Windows/Integrated Authentication when possible:
 ```xml
 <Project Sdk="Microsoft.NET.Sdk">
   <ItemGroup>
-    <PackageReference Include="JD.Efcpt.Build" Version="x.x.x" />
+    <PackageReference Include="JD.Efcpt.Build" Version="PACKAGE_VERSION" />
   </ItemGroup>
 
   <!-- No connection string config needed! -->
@@ -380,7 +380,7 @@ Complete example for an ASP.NET Core project:
   </PropertyGroup>
 
   <ItemGroup>
-    <PackageReference Include="JD.Efcpt.Build" Version="x.x.x" />
+    <PackageReference Include="JD.Efcpt.Build" Version="PACKAGE_VERSION" />
     <PackageReference Include="Microsoft.EntityFrameworkCore.SqlServer" Version="8.0.0" />
   </ItemGroup>
 

docs/user-guide/getting-started.md

@@ -28,7 +28,7 @@ The SDK approach provides the cleanest project files.
 Use the SDK in your project file with the version specified inline:
 
 ```xml
-<Project Sdk="JD.Efcpt.Sdk/1.0.0">
+<Project Sdk="JD.Efcpt.Sdk/PACKAGE_VERSION">
     <PropertyGroup>
         <TargetFramework>net8.0</TargetFramework>
         <ImplicitUsings>enable</ImplicitUsings>
@@ -56,7 +56,7 @@ Add JD.Efcpt.Build to your application project (the project that should contain
 
 ```xml
 <ItemGroup>
-  <PackageReference Include="JD.Efcpt.Build" Version="x.x.x" />
+  <PackageReference Include="JD.Efcpt.Build" Version="PACKAGE_VERSION" />
   <PackageReference Include="Microsoft.EntityFrameworkCore.SqlServer" Version="10.0.0" />
 </ItemGroup>
 ```