dotnet-release-management

name	dotnet-release-management
category	operations
subcategory	release
description	Manages .NET release lifecycle. NBGV versioning, SemVer, changelogs, pre-release, branching.
license	MIT
targets	["*"]
tags	["foundation","dotnet","skill"]
version	0.0.1
author	dotnet-agent-harness
invocable	true
claudecode	{"allowed-tools":["Read","Grep","Glob","Bash","Write","Edit"]}
codexcli	{"short-description":".NET skill guidance for foundation tasks"}
opencode	{"allowed-tools":["Read","Grep","Glob","Bash","Write","Edit"]}
copilot	{}
geminicli	{}
antigravity	{}

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

```json

### version.json Configuration

```json

{
  "$schema": "https://raw.githubusercontent.com/dotnet/Nerdbank.GitVersioning/main/src/NerdBank.GitVersioning/version.schema.json",
  "version": ,
  : [
    ,
    
  ],
  : {
    : {
      : 
    },
    : 
  }
}

```text



| Field | Purpose | Example |
|-------|---------|---------|
| `version` | Base version (major.minor, optional patch) | ``, `` |
| `publicReleaseRefSpec` | Regex patterns  branches/tags that produce public versions | `[]` |
| `cloudBuild.buildNumber.enabled` | Set CI build number to calculated version | `` |
| `cloudBuild.setVersionVariables` | Export version as CI environment variables | `` |
| `nugetPackageVersion` | Override NuGet package version format | `{: 2}` |
| `assemblyVersion.precision` | Assembly version component count | ``, ``, ``, `` |
| `inherit` | Inherit from parent directory version.json | `` |



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

```json

version.json: : 

Commit :
  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)

```json

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



```json

{
  : ,
  : [
    ,
    
  ]
}

```text

| Branch/Ref | Computed Version | Notes |
|-----------|-----------------|-------|
| `main` (public) | `1.2.5-beta` | Public pre-release, height=5 |
| `feature/foo` (non-public) | `1.2.5-beta.gcommithash` | Includes git  suffix |
| Tag `v1.2.5` (public) | `1.2.5` | Remove `-beta` before tagging |

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

```json

{
  : 
}

```json



```bash


nbgv get-version


nbgv get-version -v NuGetPackageVersion
nbgv get-version -v SemVer2


nbgv prepare-release


nbgv cloud

```text



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

```json

repo-root/
  version.json              <- { :  }
  src/
    LibraryA/
      version.json          <- { : , :  }
    LibraryB/
      version.json          <- { : , :  }

```json

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

---





SemVer 2.0 specifies version format `MAJOR.MINOR.PATCH`:

| Change Type | Version Bump | Examples |
|-------------|-------------|----------|
| Breaking API changes | **Major** | Removing public types/members, changing method signatures, renaming namespaces |
| New features (backward compatible) | **Minor** | Adding public types/members, new extension methods, new overloads |
| Bug fixes (backward compatible) | **Patch** | Fixing incorrect behavior, performance improvements, internal refactors |



| Change | Breaking? | Notes |
|--------|-----------|-------|
| Remove public  | Yes (Major) | Consumers referencing it will fail to compile |
| Remove public method | Yes (Major) | Direct callers will fail |
| Add required parameter to public method | Yes (Major) | Existing callers  not supply it |
| Add optional parameter to public method | No (Minor) | Binary compatible but source-breaking  callers using named arguments |
| Change   | Yes (Major) | Binary and  breaking |
| Add new public  | No (Minor) | No existing code affected |
| Add new overload | No (Minor) | Existing calls still resolve |
| Change internal implementation | No (Patch) | No public API change |
| Change default value of optional parameter | No (Patch) | Binary compatible (value embedded at call site on recompile) |
| Seal a previously unsealed class | Yes (Major) | Consumers inheriting from it will fail |
| Make a virtual method non-virtual | Yes (Major) | Consumers overriding it will fail |



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

```xml

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

```text

---



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



| Approach | Format | Best For |
|----------|--------|----------|
| SemVer (feature-driven) | `1.2.3` | Installed desktop/mobile apps with user-visible versioning |
| CalVer (calendar-based) | `2024.1.15` | SaaS apps with continuous deployment |
| Build number | `1.2.3+42` | CI-driven versioning with build metadata |
| NBGV height | `1.2.42` | Automated versioning from git commits |



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

```text

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

```text

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



For continuously deployed services, version stamping aids troubleshooting:

```xml

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

```text

Read at runtime:

```csharp

var version = typeof(Program).Assembly
    .GetCustomAttribute<System.Reflection.AssemblyInformationalVersionAttribute>()
    ?.InformationalVersion;
// Returns 

```text

---





The [Keep a Changelog](https://keepachangelog.com/) format is a widely adopted standard:

```markdown



All notable changes to this project will be documented  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).




- Widget caching support  improved throughput




- Fluent API  widget configuration
- Batch processing support


- Improved error messages  invalid widget states


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


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




- 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

```text



| Section | Purpose |
|---------|---------|
| `Added` | New features |
| `Changed` | Changes to existing functionality |
| `Deprecated` | Features that will be removed  future versions |
| `Removed` | Features removed  this release |
| `Fixed` | Bug fixes |
| `Security` | Vulnerability fixes |



[git-cliff](https://git-cliff.org/) generates changelogs from conventional commits:

```bash


cargo install git-cliff


git cliff --output CHANGELOG.md


git cliff --unreleased --output CHANGELOG.md


git cliff --tag v1.2.0 --unreleased

```markdown

Configure `cliff.toml`  .NET conventional commit patterns:

```toml


[changelog]
header = 
body = v%Y-%m-%dgroup
trim = 

[git]
conventional_commits = 
filter_unconventional = 
commit_parsers = [
    { message = , group =  },
    { message = , group =  },
    { message = , group =  },
    { message = , group =  },
    { message = , group =  },
    { message = , group =  },
    { message = , skip =  },
    { message = , skip =  },
    { message = , skip =  },
]

```text



```text

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

Breaking change  body:
feat: redesign widget API

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

```text

| Prefix | SemVer Impact | Changelog Section |
|--------|--------------|-------------------|
| `feat:` | Minor | Added |
| `fix:` | Patch | Fixed |
| `feat!:` or `BREAKING CHANGE:` | Major | Breaking Changes |
| `perf:` | Patch | Changed |
| `refactor:` | Patch | Changed |
| `docs:` | None | Documentation |
| `chore:` | None | (skipped) |

---





```text

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 ( needed)
1.0.0          Stable release

```text



```bash

















```json



For projects not using NBGV:

```xml

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

```text

Override from CI:

```bash


dotnet pack /p:VersionSuffix=


dotnet pack

```text



NuGet follows SemVer 2.0 pre-release precedence:

```text

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

```text

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

---





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

```text

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

```text

```bash


git tag -a v1.0.0 -m 
git push origin v1.0.0

```bash

**Best :** Libraries, small teams, continuous delivery.



Create a release branch  stabilization  `main` continues development.

```text

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