dotnet-release-management

Release lifecycle management for .NET projects: Nerdbank.GitVersioning (NBGV) setup with version.json configuration, version height calculation, and public release vs pre-release modes; SemVer 2.0 strategy for .NET libraries (when to bump major/minor/patch, API compatibility considerations) and applications (build metadata, deployment versioning); changelog generation (Keep a Changelog format, auto-generation with git-cliff and conventional commits); pre-release version workflows (alpha, beta, rc, stable progression); and release branching patterns (release branches, hotfix branches, trunk-based releases with tags).

Version assumptions: .NET 8.0+ baseline. Nerdbank.GitVersioning 3.6+ (current stable). SemVer 2.0 specification.

Scope

• Nerdbank.GitVersioning (NBGV) setup and version height
• SemVer 2.0 strategy for libraries and applications
• Changelog generation (Keep a Changelog, git-cliff)
• Pre-release version workflows (alpha, beta, rc, stable)
• Release branching patterns (release branches, trunk-based)

Out of scope

• CI/CD NuGet push and deployment workflows — see [skill:dotnet-gha-publish] and [skill:dotnet-ado-publish]
• GitHub Release creation and asset attachment — see [skill:dotnet-github-releases]
• NuGet package metadata and signing — see [skill:dotnet-nuget-authoring]
• Project-level configuration (SourceLink, CPM) — see [skill:dotnet-project-structure]

Cross-references: [skill:dotnet-gha-publish] for CI publish workflows, [skill:dotnet-ado-publish] for ADO publish workflows, [skill:dotnet-nuget-authoring] for NuGet package versioning properties.

NBGV (Nerdbank.GitVersioning)

NBGV calculates deterministic version numbers from git history. The version is derived from a version.json file and the git commit height (number of commits since the version was set), producing unique versions for every commit without manual version bumps.

Installation

# Install NBGV CLI tool
dotnet tool install --global nbgv

# Initialize NBGV in a repository
nbgv install

# This creates version.json at the repo root

version.json Configuration

{
  "$schema": "https://raw.githubusercontent.com/dotnet/Nerdbank.GitVersioning/main/src/NerdBank.GitVersioning/version.schema.json",
  "version": "1.0",
  "publicReleaseRefSpec": [
    "^refs/heads/main$",
    "^refs/tags/v\\d+\\.\\d+(\\.\\d+)?(-.*)?$"
  ],
  "cloudBuild": {
    "buildNumber": {
      "enabled": true
    },
    "setVersionVariables": true
  }
}

version.json Field Reference

How Version Height Works

NBGV counts the number of commits since the version field was last changed in version.json. This count becomes the patch version:

version.json: "version": "1.2"

Commit history:
  abc1234  feat: add caching          -> 1.2.3
  def5678  fix: null check            -> 1.2.2
  ghi9012  chore: update deps         -> 1.2.1
  jkl3456  Bump version to 1.2        -> 1.2.0  (version.json changed here)

The version height ensures every commit has a unique version without manual intervention.

Pre-Release vs Public Release

{
  "version": "1.2-beta",
  "publicReleaseRefSpec": [
    "^refs/heads/main$",
    "^refs/tags/v\\d+\\.\\d+(\\.\\d+)?(-.*)?$"
  ]
}

To release a stable version, remove the pre-release suffix from version.json before the release commit:

{
  "version": "1.2"
}

NBGV CLI Commands

# Show the current calculated version
nbgv get-version

# Show specific version properties
nbgv get-version -v NuGetPackageVersion
nbgv get-version -v SemVer2

# Prepare for a release (creates release branch, bumps version)
nbgv prepare-release

# Set version variables for CI
nbgv cloud

Monorepo NBGV Configuration

For monorepos with independently versioned projects, place version.json in each project directory and use inherit:

repo-root/
  version.json              <- { "version": "1.0" }
  src/
    LibraryA/
      version.json          <- { "version": "2.3", "inherit": true }
    LibraryB/
      version.json          <- { "version": "1.1-beta", "inherit": true }

The inherit field pulls settings (like publicReleaseRefSpec and cloudBuild) from the parent version.json while overriding the version number.

SemVer Strategy for .NET Libraries

When to Bump Versions

SemVer 2.0 specifies version format MAJOR.MINOR.PATCH:

.NET-Specific Breaking Change Considerations

API Compatibility Validation

Use EnablePackageValidation to catch accidental breaking changes. For full package validation setup, see [skill:dotnet-nuget-authoring].

<PropertyGroup>
  <EnablePackageValidation>true</EnablePackageValidation>
  <PackageValidationBaselineVersion>1.0.0</PackageValidationBaselineVersion>
</PropertyGroup>

SemVer Strategy for Applications

Applications (web apps, desktop apps, services) have different versioning considerations than libraries because they do not have public API consumers.

Application Versioning Approaches

Build Metadata

SemVer 2.0 allows + suffixed build metadata that does not affect version precedence:

1.2.3+build.42        Build number
1.2.3+abcdef          Git commit hash
1.2.3+2024.01.15      Build date
1.2.3-beta.1+42       Pre-release with build metadata

Build metadata is useful for tracing a deployed binary back to its source commit. NBGV appends git metadata automatically.

Deployment Versioning

For continuously deployed services, version stamping aids troubleshooting:

<PropertyGroup>
  <!-- Embed full version in assembly for runtime introspection -->
  <InformationalVersion>1.2.3+abcdef.2024-01-15</InformationalVersion>
</PropertyGroup>

Read at runtime:

var version = typeof(Program).Assembly
    .GetCustomAttribute<System.Reflection.AssemblyInformationalVersionAttribute>()
    ?.InformationalVersion;
// Returns "1.2.3+abcdef.2024-01-15"

Changelog Generation

Keep a Changelog Format

The Keep a Changelog format is a widely adopted standard:

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added
- Widget caching support for improved throughput

## [1.2.0] - 2024-03-15

### Added
- Fluent API for widget configuration
- Batch processing support

### Changed
- Improved error messages for invalid widget states

### Fixed
- Memory leak in widget pool under high concurrency
- Timezone handling in scheduled widget operations

### Deprecated
- `Widget.Create()` static method -- use `WidgetBuilder` instead

## [1.1.0] - 2024-01-10

### Added
- Widget serialization support

[Unreleased]: https://github.com/mycompany/widgets/compare/v1.2.0...HEAD
[1.2.0]: https://github.com/mycompany/widgets/compare/v1.1.0...v1.2.0
[1.1.0]: https://github.com/mycompany/widgets/releases/tag/v1.1.0

Section Types

Auto-Generation with git-cliff

git-cliff generates changelogs from conventional commits:

# Install git-cliff
cargo install git-cliff

# Generate changelog for all versions
git cliff --output CHANGELOG.md

# Generate changelog for unreleased changes only
git cliff --unreleased --output CHANGELOG.md

# Generate notes for a specific tag range
git cliff --tag v1.2.0 --unreleased

Configure cliff.toml for .NET conventional commit patterns:

# cliff.toml
[changelog]
header = """
# Changelog\n
All notable changes to this project will be documented in this file.\n
"""
body = """
{% if version %}\
    ## [{{ version | trim_start_matches(pat="v") }}] - {{ timestamp | date(format="%Y-%m-%d") }}
{% else %}\
    ## [Unreleased]
{% endif %}\
{% for group, commits in commits | group_by(attribute="group") %}
    ### {{ group | upper_first }}
    {% for commit in commits %}
        - {{ commit.message | upper_first }}\
    {% endfor %}
{% endfor %}\n
"""
trim = true

[git]
conventional_commits = true
filter_unconventional = true
commit_parsers = [
    { message = "^feat", group = "Added" },
    { message = "^fix", group = "Fixed" },
    { message = "^perf", group = "Changed" },
    { message = "^refactor", group = "Changed" },
    { message = "^docs", group = "Documentation" },
    { message = "^chore\\(deps\\)", group = "Dependencies" },
    { message = "^chore", skip = true },
    { message = "^ci", skip = true },
    { message = "^test", skip = true },
]

Conventional Commit Format

feat: add widget caching support
fix: correct timezone handling in scheduler
feat!: rename Widget.Create() to WidgetBuilder.Build()
chore(deps): update System.Text.Json to 8.0.5
docs: update API reference for caching

Breaking change in body:
feat: redesign widget API

BREAKING CHANGE: Widget.Create() has been removed. Use WidgetBuilder instead.

Pre-Release Version Workflows

Standard Pre-Release Progression

alpha -> beta -> rc -> stable

1.0.0-alpha.1  Early development, API unstable
1.0.0-alpha.2  Continued alpha iteration
1.0.0-beta.1   Feature-complete, API stabilizing
1.0.0-beta.2   Beta bug fixes
1.0.0-rc.1     Release candidate, final validation
1.0.0-rc.2     RC bug fix (if needed)
1.0.0          Stable release

NBGV Pre-Release Workflow

# Start with pre-release suffix in version.json
# version.json: { "version": "1.0-alpha" }
# Produces: 1.0.1-alpha, 1.0.2-alpha, ...

# Promote to beta
# Edit version.json: { "version": "1.0-beta" }
# Produces: 1.0.1-beta, 1.0.2-beta, ...

# Promote to rc
# Edit version.json: { "version": "1.0-rc" }
# Produces: 1.0.1-rc, 1.0.2-rc, ...

# Promote to stable
# Edit version.json: { "version": "1.0" }
# Produces: 1.0.1, 1.0.2, ...

Manual Pre-Release Workflow

For projects not using NBGV:

<!-- In .csproj or Directory.Build.props -->
<PropertyGroup>
  <VersionPrefix>1.0.0</VersionPrefix>
  <VersionSuffix>beta.1</VersionSuffix>
  <!-- Produces: 1.0.0-beta.1 -->
</PropertyGroup>

Override from CI:

# CI sets the pre-release suffix
dotnet pack /p:VersionSuffix="beta.$(BUILD_NUMBER)"

# Stable release: omit VersionSuffix
dotnet pack

NuGet Pre-Release Ordering

NuGet follows SemVer 2.0 pre-release precedence:

1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-alpha.2
1.0.0-alpha.2 < 1.0.0-beta
1.0.0-beta < 1.0.0-beta.1
1.0.0-rc.1 < 1.0.0

Numeric identifiers are compared as integers; alphabetic identifiers are compared lexically.

Release Branching Patterns

Trunk-Based with Tags

The simplest release model. All development happens on main, releases are marked with tags.

main:  A -- B -- C -- D -- E -- F -- G
                 |              |
              v1.0.0         v1.1.0

# Tag and push for release
git tag -a v1.0.0 -m "Release v1.0.0"
git push origin v1.0.0

Best for: Libraries, small teams, continuous delivery.

Release Branches

Create a release branch for stabilization while main continues development.

main:      A -- B -- C -- D -- E -- F -- G
                      \
release/1.0:           C' -- D' -- E'
                              |
                           v1.0.0

# Create release branch
git checkout -b release/1.0 main

# Stabilize on release branch (bug fixes only)
git commit -m "fix: correct null check in widget pool"

# Tag and release
git tag -a v1.0.0 -m "Release v1.0.0"
git push origin release/1.0 v1.0.0

# Merge fixes back to main
git checkout main
git merge release/1.0

Best for: Products with support contracts, LTS versions, teams needing parallel development and stabilization.

NBGV prepare-release

NBGV automates release branch creation and version bumping:

# Creates release/v1.0 branch, bumps main to 1.1-alpha
nbgv prepare-release

# What this does:
# 1. Creates branch "release/v1.0" from current commit
# 2. On release branch: removes pre-release suffix (version: "1.0")
# 3. On main: bumps to "1.1-alpha" (next development version)

Hotfix Branches

Emergency fixes for released versions:

main:         A -- B -- C -- D -- E
                         \
release/1.0:              C' -- v1.0.0
                                  \
hotfix/1.0.1:                      F' -- v1.0.1

# Branch from the release tag
git checkout -b hotfix/1.0.1 v1.0.0

# Fix the critical issue
git commit -m "fix: critical security vulnerability in auth handler"

# Tag and release the hotfix
git tag -a v1.0.1 -m "Hotfix v1.0.1"
git push origin hotfix/1.0.1 v1.0.1

# Merge hotfix back to main
git checkout main
git merge hotfix/1.0.1

Branching Pattern Comparison

For most .NET open-source libraries, trunk-based with tags and NBGV is sufficient. Reserve release branches for products that maintain multiple supported versions simultaneously.

Agent Gotchas

1. NBGV version.json uses major.minor only (not major.minor.patch) — the patch version is calculated from commit height. Setting "version": "1.2.3" fixes the patch to 3, defeating the purpose of automatic versioning.

2. NBGV requires git history to calculate version height — shallow clones (git clone --depth 1) produce incorrect versions. In CI, use fetch-depth: 0 with actions/checkout to get full history.

3. publicReleaseRefSpec patterns are regex, not globs — use ^refs/heads/main$ not main. Missing anchors will match unintended refs.

4. SemVer pre-release ordering is lexical for non-numeric segments — alpha < beta < rc because of alphabetical comparison. Numeric segments are compared as integers, so beta.2 < beta.10 (because 2 < 10). Do not assume lexical ordering for numeric identifiers.

5. Do not use CalVer for NuGet libraries — NuGet resolution depends on SemVer ordering. CalVer versions like 2024.1.0 work mechanically but violate consumer expectations for API stability signals.

6. VersionPrefix + VersionSuffix combine to form Version — setting all three causes conflicts. Use either Version alone or VersionPrefix/VersionSuffix together, not both.

7. Keep a Changelog [Unreleased] section must be updated before release — move entries from [Unreleased] to the new version section, update comparison links, and add a new empty [Unreleased] section.

8. nbgv prepare-release modifies both the new branch and the current branch — it bumps the version on the current branch to the next minor. Run it from the branch you want to continue development on (usually main).