Git2SemVer Versioning

Git2SemVer is a Visual Studio and developer friendly Semantic Versioning framework for .NET solution/project versioning and changelog generation. It works the same with both Visual Studio and dotnet CLI builds. Every build, on both developer boxes and the build system, get traceable build numbering (no commit counting).

Quick introduction

You:

• Mark a release's commit by adding a git tag like v1.2.3.
• Use separate branches to separate release builds and non-release builds (e.g: main and/or release/A may build release builds while feature/A or dev/A may build pre-release builds).
• Use Conventional Commit mesages like fix: fixed crash on shutdown to mark commits with fixes, features, and/or breaking changes.

Git2SemVer automatically, on every build, provides:

• Semantic versioning:
  • File version
  • Assembly version
  • Informational version
  • Package version (NuGet package version and filename)
  • Other MSBuild version properties
  • Pre-release identifier like alpha/beta/rc (from branch name and if a build system build)
• Build number - even on dev boxes
• Host adaptive version formating like:
  • When building a developer's box - All builds are pre-release alpha builds and the pre-release metadata automatically includes the host machine's name.
  • Different build number sources and formating to best suit a host's (e.g: GitHub Workflow and TeamCity) capabilities.

Git2SemVer also detects and executes an optional C# script that can change any part of the versioning.

It can be configured for any mix of solution versioning and individual project versioning without external build-time tools. No build system version generation steps are needed, keeps developer and build environments simple and aligned.

An example git workflow from a release 1.2.3 to the next release 2.0.0:

gitGraph
        commit id:"1.2.3+99"
        
        commit id:"1.2.3+100" tag:"1.2.3"
        branch feature/berry order: 1
        checkout feature/berry
        commit id:"1.2.3-beta.101"

        checkout main
        commit id:"1.2.3-alpha.102"
        branch feature/peach order: 3
        checkout feature/berry

        branch develop/berry order: 2
        checkout develop/berry
        commit id:"feat:berry 1.3.0-alpha.103"
        checkout feature/berry
        merge develop/berry id:"1.3.0-beta.104"
        checkout main
        merge feature/berry id:"1.3.0+105"

        checkout feature/peach
        commit id:"fix:bug1 1.2.3-beta.106"
        commit id:"feat!:peach 2.0.0-beta.107"
        checkout main
        merge feature/peach id:"2.0.0+108" tag:"v2.0.0"

        commit id:"2.0.1-beta.108"

Quick links

• Getting Started
• Default Versioning
• Usage
  • Workflow
  • Release Tagging
  • Branch naming
  • Build Hosts
  • C# Script

Features

	Conventional Commits Use conventional commits to automate both changelog generation and get semantic versioning for free.
	Visual Studio and .NET developer friendly Versioning on every Visual Studio or dotnet CLI build without exernal tools. Just build.
	Semantic Versioning Industry standard Semantic Version compliance. Supports initial development versioning.
	Environment Parity Visual Studio, VS Code, and dotnet CLI are all the same to Git2SemVer. Build system and developer environments all get versioning without custom build steps, tools, or scripts.
#	Build Numbering Automatic build numbering on all developer boxes and build system builds. Full traceability. Build height NOT used.
	C# Scripting No limits customisable by built-in C# scripting with a versioning API.
	Build Host Adaptive Versioning The versioning adapts according to the build host. e.g: Automatically uses TeamCity build counter for build number and on dev boxes adds machine name metadata like: 1.2.3-beta.3456 vs 1.2.3-alpha.JohnsPC.3456.
	Git Workflow Agnostic No Git workflow configuration required. It works the same for GitFlow and GitHub Flow.
	TeamCity Integration Automatic build system detection with server build number (label) updated with a build version specifically adapted for TeamCity.
	GitHub Workflows Built in support for builds using GitHub Actions. Constructs build number from run and run attempt numbers and adapts the version for GitHub builds.