Version Release Fix - October 2025

Issue Summary

The release version was stuck on 1.0.1 and not incrementing with new commits to the main branch. This prevented:

New releases from being created
Updated packages from being deployed to NuGet.org
Beta and alpha packages from having correct version numbers for PR builds

Root Cause

The GitVersion.yml configuration file had the next-version field hardcoded to 1.0.1:

mode: Mainline
next-version: 1.0.1  # ← This was preventing GitVersion from auto-calculating versions

GitVersion is designed to automatically calculate versions based on:

Git tags (e.g., v1.0.1)
Branch configuration (e.g., increment: Minor on main branch)
Commit history since the last tag

By hardcoding next-version: 1.0.1, we prevented GitVersion from incrementing past this base version, even though the repository had the tag v1.0.1 at an older commit and new commits on main.

Solution Applied

Removed the next-version field entirely from GitVersion.yml:

mode: Mainline
# next-version removed - GitVersion will auto-calculate from tags
branches:
  main:
    increment: Minor  # Auto-increments minor version

Now GitVersion will:

Find the latest tag (v1.0.1)
Count commits since that tag
Apply the increment strategy (Minor) to calculate the next version
Automatically produce 1.1.0 (or higher) for new commits on main

Impact of Fix

After this PR is merged to main:

✅ GitVersion will automatically calculate the next version as 1.1.0 (since increment: Minor)
✅ Clean packages will be published to NuGet.org with the auto-calculated version
✅ Packages will be published to GitHub Packages
✅ No manual version updates needed - GitVersion handles it automatically
✅ Future commits to main will continue to auto-increment

How Versioning Works Now (Automatic)

GitVersion automatically manages versioning:

For Minor Releases (Automatic)

Just merge to main - GitVersion will increment: 1.0.1 → 1.1.0 → 1.2.0 → ...

For Major Releases

Create a tag manually when needed:

git tag v2.0.0
git push --tags

For Patch Releases

Change the increment strategy temporarily in GitVersion.yml:

branches:
  main:
    increment: Patch  # Changes to patch increment

Then merge to main for 1.1.0 → 1.1.1 → 1.1.2 → ...

Why Automatic Versioning Is Better

✅ No manual updates - versions increment automatically with each merge
✅ No version conflicts - GitVersion calculates based on actual git history
✅ Semantic versioning - respects the increment strategy (Major/Minor/Patch)
✅ Consistent - works the same way across all branches

Verification

You can verify the version that will be generated by running:

# Install GitVersion tool
dotnet tool install --global GitVersion.Tool --version 5.*

# Check the version that will be generated
dotnet-gitversion /showvariable SemVer

GitVersion.yml - Removed next-version field to enable auto-versioning
PACKAGE-BUILDING.md - Documentation updated to explain automatic versioning
.github/workflows/cd.yml - CD pipeline that creates releases
.github/workflows/ci.yml - CI pipeline that publishes to GitHub Packages

CI/CD Pipeline Status

Both pipelines are working correctly:

CI Pipeline: Successfully builds and publishes pre-release packages to GitHub Packages
CD Pipeline: Successfully creates releases and publishes to NuGet.org

GitVersion will now automatically calculate versions based on tags and commits.