Adopt pure 3-segment SemVer versioning

- Remove BuildNumber append from VersionPrefix; use FileVersion for
  4-segment build traceability instead
- Resolve-version now checks tag existence for release idempotency:
  only bumped versions trigger a release, repeated pushes are CI-only
- Simplify full_version to equal version (no run_number suffix)
- Remove BuildNumber concatenation from NUKE GenerateReleaseManifest
- Update docs and README to reflect SemVer tags (v0.2.0 not v0.2.0.42)

Made-with: Cursor

Author: Hongwei-MB

.github/workflows/ci.yml

@@ -59,30 +59,29 @@ jobs:
 
           SHA="$(git rev-parse HEAD)"
 
+          TAG="v$VERSION"
+
           IS_RELEASE="false"
           if [ "${{ github.event_name }}" != "pull_request" ] && [ "${{ github.ref }}" = "refs/heads/main" ]; then
-            IS_RELEASE="true"
-          fi
-
-          if [ "$IS_RELEASE" = "true" ]; then
-            FULL_VERSION="${VERSION}.${{ github.run_number }}"
-          else
-            FULL_VERSION="$VERSION"
+            git fetch --tags --force
+            if git ls-remote --tags origin "refs/tags/$TAG" | grep -q "$TAG"; then
+              echo "::notice::Tag $TAG already exists. Version not bumped — skipping release."
+            else
+              IS_RELEASE="true"
+            fi
           fi
-          TAG="v$FULL_VERSION"
 
           echo "version=$VERSION" >> "$GITHUB_OUTPUT"
-          echo "full_version=$FULL_VERSION" >> "$GITHUB_OUTPUT"
+          echo "full_version=$VERSION" >> "$GITHUB_OUTPUT"
           echo "tag=$TAG" >> "$GITHUB_OUTPUT"
           echo "sha=$SHA" >> "$GITHUB_OUTPUT"
           echo "is_release=$IS_RELEASE" >> "$GITHUB_OUTPUT"
-          echo "Resolved: version=$VERSION full_version=$FULL_VERSION tag=$TAG sha=$SHA is_release=$IS_RELEASE"
+          echo "Resolved: version=$VERSION tag=$TAG sha=$SHA is_release=$IS_RELEASE"
 
       - name: Version summary
         shell: bash
         run: |
           VERSION="${{ steps.resolve.outputs.version }}"
-          FULL_VERSION="${{ steps.resolve.outputs.full_version }}"
           IS_RELEASE="${{ steps.resolve.outputs.is_release }}"
           SHA="${{ steps.resolve.outputs.sha }}"
           TAG="${{ steps.resolve.outputs.tag }}"
@@ -119,8 +118,7 @@ jobs:
             echo ""
             echo "| Property | Value |"
             echo "|----------|-------|"
-            echo "| **Version** | \`$FULL_VERSION\` |"
-            echo "| **Base Version** | \`$VERSION\` |"
+            echo "| **Version** | \`$VERSION\` |"
             echo "| **Tag** | \`$TAG\` |"
             echo "| **Previous Tag** | \`$PREV_TAG\` |"
             echo "| **Bump Type** | **$BUMP** |"
@@ -167,7 +165,7 @@ jobs:
     runs-on: ${{ matrix.os }}
     timeout-minutes: 30
     env:
-      BuildNumber: ${{ needs.resolve-version.outputs.is_release == 'true' && github.run_number || '' }}
+      BuildNumber: ${{ github.event_name != 'pull_request' && github.run_number || '' }}
     strategy:
       fail-fast: false
       matrix: ${{ fromJSON(needs.resolve-version.outputs.build_matrix) }}

Directory.Build.props

@@ -13,10 +13,11 @@
 
 
   <!-- Explicit version: single source of truth for the entire solution.
-       Bump this value via PR when preparing a new release. -->
+       Bump this value via PR when preparing a new release.
+       Release is triggered only when this version differs from the latest git tag. -->
   <PropertyGroup>
     <VersionPrefix>0.2.0</VersionPrefix>
-    <VersionPrefix Condition="'$(BuildNumber)' != ''">$(VersionPrefix).$(BuildNumber)</VersionPrefix>
+    <FileVersion Condition="'$(BuildNumber)' != ''">$(VersionPrefix).$(BuildNumber)</FileVersion>
   </PropertyGroup>
 
   <!-- Local builds default to prerelease to avoid confusion with stable releases.

README.md

@@ -41,7 +41,7 @@ On **pull requests**, only a fast linux build + test runs. On **main**, the full
 | **NuGet Publishing** | Auto-push to NuGet.org with SHA256 manifest verification |
 | **Installer Packages** | Platform-specific zip archives attached to GitHub Releases |
 | **Version from Code** | `VersionPrefix` in `Directory.Build.props` is the single source of truth |
-| **Four-Part Release Tags** | `v0.2.0.42` format ensures unique tags per build |
+| **SemVer Release Tags** | `v0.2.0` format — release triggers only when version is bumped |
 | **CodeQL Security** | Automated vulnerability scanning on every push and weekly |
 | **Graceful Degradation** | Missing NuGet key? Skipped. No docs config? Skipped. Nothing breaks. |
 
@@ -94,11 +94,12 @@ The pipeline runs automatically. When `build-and-test` completes, go to **Action
 
 ## Version Management
 
-Versions follow a simple rule:
+Versions follow SemVer (3-segment `Major.Minor.Patch`):
 
-- **CI appends the build number** on release: `0.2.0` becomes `0.2.0.42`
-- **Tags are created automatically**: `v0.2.0.42`
-- No manual tagging. No version input fields. The single source of truth is `VersionPrefix` in `Directory.Build.props`.
+- **`VersionPrefix` in `Directory.Build.props`** is the single source of truth (e.g., `0.2.0`)
+- **Tags are created automatically**: `v0.2.0` — release triggers only when the tag doesn't exist yet
+- **`FileVersion`** includes the CI build number for traceability (e.g., `0.2.0.42`), visible in DLL properties
+- No manual tagging. No version input fields. Bump `VersionPrefix` via PR to trigger a release.
 
 ### Version commands
 
@@ -146,7 +147,7 @@ env:
 
 ## Concurrency
 
-Multiple `CI and Release` runs execute **in parallel by default**. Each run gets a unique `run_number`, so versions never conflict.
+Multiple `CI and Release` runs execute **in parallel by default**.
 
 To serialize runs on the same branch (only one active at a time), set repository variables in **Settings > Secrets and variables > Actions > Variables**:
 

build/BuildTask.Targets.ReleaseManifest.cs

@@ -52,13 +52,7 @@ string ReadVersionPrefixFromProps()
         var match = Regex.Match(content, @"<VersionPrefix>\s*([^<]+?)\s*</VersionPrefix>", RegexOptions.Singleline);
         if (!match.Success)
             throw new InvalidOperationException($"<VersionPrefix> not found in {DirectoryBuildPropsFile}");
-        var version = match.Groups[1].Value.Trim();
-
-        var buildNumber = Environment.GetEnvironmentVariable("BuildNumber");
-        if (!string.IsNullOrWhiteSpace(buildNumber))
-            version = $"{version}.{buildNumber}";
-
-        return version;
+        return match.Groups[1].Value.Trim();
     }
 
     static string GetGitHeadSha()

docs/github-workflows-guide.md

@@ -25,11 +25,11 @@ For a quick release walkthrough, see: [Quick Start Release](quick-start-release.
 
 ### `CI and Release`
 - Triggers: `push` to `main`, `pull_request` targeting `main`, manual `workflow_dispatch`
-- Concurrency: **Parallel by default** — multiple pushes can run simultaneously (`run_number` is naturally unique, no version conflicts)
+- Concurrency: **Parallel by default** — multiple pushes can run simultaneously
   - For serial execution: Settings → Variables → set `CI_SERIAL=true` (queues by branch)
   - To cancel older runs: set `CI_CANCEL_IN_PROGRESS=true`
 - PR behavior: Runs Format Check + Build + Test + Coverage Report on ubuntu (with prerelease suffix)
-- main push behavior: Full-platform matrix Build + Test + Pack + Publish + PackageApp → approval → NuGet push + SBOM + Attestation + tag + GitHub Release → documentation deployment
+- main push behavior: If `VersionPrefix` has been bumped (tag doesn't exist yet), triggers full-platform matrix Build + Test + Pack + Publish + PackageApp → approval → NuGet push + SBOM + Attestation + tag + GitHub Release → documentation deployment. Otherwise, runs CI-only (build + test).
 - Artifacts: Test results (with PR annotations), coverage reports, NuGet packages (with release manifest), platform installer zips, SBOM
 
 ### `CodeQL`
@@ -42,9 +42,9 @@ For a quick release walkthrough, see: [Quick Start Release](quick-start-release.
 ## 2) Job Details
 
 ### `resolve-version`
-- Reads `VersionPrefix` from `Directory.Build.props`, validates semver format
-- Determines if this is a release (main push = true, PR = false)
-- Computes the build matrix: PR uses ubuntu only, main push includes win/linux/osx
+- Reads `VersionPrefix` from `Directory.Build.props`, validates semver format (3-segment: `Major.Minor.Patch`)
+- Determines if this is a release: main push + tag `v{version}` does not exist yet = release; otherwise CI-only
+- Computes the build matrix: PR uses ubuntu only, release includes win/linux/osx
 
 ### `build-and-test`
 - Matrix build: each platform runs Build + Test
@@ -80,7 +80,7 @@ For a quick release walkthrough, see: [Quick Start Release](quick-start-release.
    Approve the `release` environment.
 
 3. Check the Releases page:
-   - A tag was created (e.g., `v0.2.0.42`)
+   - A tag was created (e.g., `v0.2.0`)
    - The GitHub Release contains platform installer zips
    - A corresponding package version exists on NuGet.org (if `NUGET_API_KEY` is configured)
 
@@ -121,7 +121,7 @@ The version comes from `VersionPrefix` in `Directory.Build.props`. CI does not a
 After making changes, merge to `main` via PR. CI automatically builds with the new version.
 
 ### Q3: Can the same version be re-published?
-Each main push generates a unique 4-segment version number (e.g., `0.2.0.42`), so the same push won't conflict. To publish a new version (e.g., `0.3.0`), modify `VersionPrefix` via PR.
+No. Each version can only be released once. If the tag `v{version}` already exists, the release is skipped and the run becomes CI-only. To publish a new version, bump `VersionPrefix` via PR (e.g., `0.2.0` → `0.3.0`).
 
 ### Q4: What is the release manifest?
 `release-manifest.json` records the SHA256 hash and version information for each NuGet package. During the release phase, package files are verified against the manifest to prevent tampering or corruption during artifact transfer.

docs/quick-start-release.md

@@ -41,7 +41,7 @@ After pushing to `main`:
 
 After a successful run, you should see:
 
-- A new tag (e.g., `v0.2.0.42`)
+- A new tag (e.g., `v0.2.0`)
 - A new GitHub Release
 - Release assets including platform installer zips (`app-linux-x64.zip`, `app-win-x64.zip`, etc.) and the SBOM file
 - A corresponding package version on NuGet.org (if `NUGET_API_KEY` is configured)
@@ -51,7 +51,7 @@ After a successful run, you should see:
 
 ## 4) Version Management (Must Read)
 
-The version comes from `VersionPrefix` in `Directory.Build.props`. CI automatically appends the build number (e.g., `0.2.0.42`).
+The version comes from `VersionPrefix` in `Directory.Build.props` — a pure 3-segment SemVer (e.g., `0.2.0`). A release is triggered only when this version differs from the latest git tag.
 
 ```bash
 ./build.sh ShowVersion                           # Show current version