Skip to content

DEMO_GUIDE.md

Latest commit

 

History

History
153 lines (112 loc) · 5.04 KB

DEMO_GUIDE.md

File metadata and controls

153 lines (112 loc) · 5.04 KB
Raw

GitVersion Demo - Getting Started Guide

Quick Start

This repository is ready to demonstrate GitVersion to your team. Here's what you need to know:

Current Repository State

The repository has been initialized with:

  • v1.0.0 - Initial release (tag on main)
  • v1.1.0 - Feature release with Divide and Power methods (tag on main)
  • v1.1.1 - Hotfix release with improved division handling (tag on main)

Multiple branches are available showing different development patterns:

  • main - Production releases (at v1.1.1)
  • develop - Integration branch for features
  • feature/add-divide - Example feature branch
  • feature/add-power - Example feature branch
  • release/1.1.0 - Example release branch
  • hotfix/fix-division-by-zero - Example hotfix branch

Prerequisites for Demo

  1. .NET SDK 9 or 10 - Already required by your team
  2. GitVersion - Either:
    • Install globally: dotnet tool install -g GitVersion.Tool
    • Or use Azure Pipelines task (no local install needed)

Demo Scenario 1: Show How GitVersion Calculates Versions

# Checkout different branches and check what version GitVersion would assign
cd c:\Users\John\repos\gitversion_demo

# Check version on main (should be based on v1.1.1 tag)
gitversion
# Output will show: SemVer = 1.1.1 (or 1.1.2-prerelease if there are unpushed commits)

# Check version on develop (should be pre-release)
git checkout develop
gitversion
# Output will show: SemVer = 1.2.0-prerelease.X (Minor bump since it's develop)

# Check version on a feature branch
git checkout feature/add-divide
gitversion
# Output will show: SemVer = 1.2.0-prerelease.X

# Check version on release branch
git checkout release/1.1.0
gitversion
# Output will show: SemVer = 1.1.0-rc.X (Release candidate)

Demo Scenario 2: Show How Version Gets Into NuGet Package

# Build the library (version automatically applied)
dotnet build src/MyLibrary/MyLibrary.csproj -c Release

# Check the generated NuGet package
ls src/MyLibrary/bin/Release/*.nupkg

# Extract and view the package metadata
# The .nupkg is a ZIP file, inside is a .nuspec file with the version
Expand-Archive src/MyLibrary/bin/Release/*.nupkg -DestinationPath temp-package -Force
Get-Content temp-package/MyLibrary.nuspec

# You'll see: <version>1.1.1</version> (or whatever the calculated version is)

Demo Scenario 3: Show the Git Workflow

# Show the complete git history with branches
git log --graph --all --oneline --decorate --all

# Point out:
# 1. Tags (v1.0.0, v1.1.0, v1.1.1) mark releases
# 2. Different branch types (feature/, release/, hotfix/)
# 3. GitVersion determines version based on branch + history
# 4. No manual version numbers in code!

Demo Scenario 4: Simulate Creating a New Version

To show how the workflow continues:

git checkout develop

# Create a new feature branch
git checkout -b feature/add-square-root

# Make a change
# (Edit src/MyLibrary/Calculator.cs - add a SquareRoot method)

git add .
git commit -m "feat: Add SquareRoot method"

# Check the version - should be pre-release
gitversion
# Output: SemVer = 1.2.0-prerelease.X

git checkout develop
git merge --no-ff feature/add-square-root

# After merge, still pre-release until released
gitversion
# Output: SemVer = 1.2.0-prerelease.X

Pain Point Addressed

Before GitVersion:

  • Developer manually edits MyLibrary.csproj → <Version>1.1.1</Version>
  • Easy to forget when in development
  • Risk of inconsistent versions between local builds and CI
  • Multiple people need to coordinate version numbers

After GitVersion:

  • Version is calculated automatically from git history
  • Same version locally and in CI/CD (reproducible)
  • No manual coordination needed
  • Follows semantic versioning automatically

Key Files to Show

  1. Directory.Build.props - Shows GitVersion integration at build level
  2. gitversion.yml - Shows version calculation rules (which branch bumps what)
  3. src/MyLibrary/MyLibrary.csproj - Shows <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
  4. azure-pipelines.yml - Shows how it integrates with CI/CD

Talking Points

  1. No Manual Version Management: Version comes from git history, not from copying numbers around
  2. Semantic Versioning Built-In: Different branch types automatically bump Major, Minor, or Patch
  3. CI/CD Friendly: Same version calculation everywhere - local, build agent, Docker
  4. Reproducible Builds: Same commit hash = same version, every time
  5. Developer Experience: Just follow branch naming conventions, GitVersion handles the rest

For Your Audience

Point out that their team:

  • Currently: Manually maintains version numbers in project files → error-prone
  • With GitVersion: Version automatically calculated from git workflow → consistent and automatic

This is especially useful for:

  • Multi-developer teams (no conflict on who updates the version)
  • CI/CD pipelines (automatic versioning in builds)
  • Semantic Versioning (automatically enforced)
  • Release management (version tags mark releases automatically)