GitVersion Cookbook: A Developer's Guide to Versioning and Git Interaction

📌 Overview

This guide provides step-by-step instructions for developers on how to interact with Git to produce correct versions using GitVersion. Based on your branch, follow the commit message conventions, pull request strategies, and Git commands to achieve the desired versioning results.

---

🔹 Branch-Based Workflow

Branch	Purpose	Version Format	Example
develop	Ongoing feature development	X.Y.Z-alpha.N	1.2.3-alpha.4
feature/*	New feature branches	X.Y.Z-feature.BranchName.N	1.2.3-feature.api-rework.3
main	Stable releases	X.Y.Z	1.2.3
release/*	Pre-release testing	X.Y.Z-beta.N	1.2.3-beta.2
hotfix/*	Urgent fixes	X.Y.Z-hotfix.N	1.2.3-hotfix.1
pull-request	Temporary branches for PRs	X.Y.Z-PullRequest.N	1.2.3-PullRequest.42

---

🚀 Typical Versioning Actions

1️⃣ Development Build (develop branch)

💡 Goal: Produce an alpha build for ongoing development.

🔹 How to Do It:

git checkout develop
git commit -m "New feature implemented"
git push

📌 Expected Version:

1.2.3-alpha.5

📌 NuGet Package Name:

MyLibrary.1.2.3-alpha.5.nupkg

✅ Best Practices:

• No need to manually bump versions.
• Every commit gets a new -alpha.N suffix.

---

2️⃣ Starting a New Feature

💡 Goal: Work on a new feature and create preview builds.

🔹 How to Do It:

git checkout develop
git checkout -b feature/api-rework
git commit -m "Initial API refactoring"
git push --set-upstream origin feature/api-rework

📌 Expected Version:

1.2.3-feature.api-rework.1

📌 NuGet Package Name:

MyLibrary.1.2.3-feature.api-rework.1.nupkg

✅ Best Practices:

• Always branch from develop.
• Feature builds don't affect develop until merged.

---

3️⃣ Making a Minor Release

💡 Goal: Release a new backward-compatible feature (X.Y+1.0).

🔹 How to Do It:

git checkout develop
git commit -m "+semver: minor Added new analytics API"
git push

📌 Expected Version:

1.3.0-alpha.1

📌 NuGet Package Name:

MyLibrary.1.3.0-alpha.1.nupkg

✅ Best Practices:

• Use +semver: minor in commit messages to bump the minor version.
• Always commit to develop.

---

4️⃣ Making a Major Release

💡 Goal: Release a breaking change (X+1.0.0).

🔹 How to Do It:

git checkout develop
git commit -m "+semver: major Breaking change to API"
git push

📌 Expected Version:

2.0.0-alpha.1

📌 NuGet Package Name:

MyLibrary.2.0.0-alpha.1.nupkg

✅ Best Practices:

• Use +semver: major in commit messages to trigger a major version bump.

---

5️⃣ Creating a Release Candidate

💡 Goal: Freeze development and prepare for a beta release.

🔹 How to Do It:

git checkout develop
git checkout -b release/1.3.0
git push --set-upstream origin release/1.3.0

📌 Expected Version:

1.3.0-beta.1

📌 NuGet Package Name:

MyLibrary.1.3.0-beta.1.nupkg

✅ Best Practices:

• Branch from develop to release/X.Y.Z.
• This version is tested before merging into main.

---

6️⃣ Releasing a Stable Version

💡 Goal: Deploy a final release.

🔹 How to Do It:

git checkout main
git merge release/1.3.0
git tag v1.3.0
git push --tags

📌 Expected Version:

1.3.0

📌 NuGet Package Name:

MyLibrary.1.3.0.nupkg

✅ Best Practices:

• Always tag stable releases (vX.Y.Z).
• Tags prevent main from using commit count (X.Y.Z-N).

---

7️⃣ Fixing a Critical Bug (hotfix/*)

💡 Goal: Apply an urgent fix to a released version.

🔹 How to Do It:

git checkout main
git checkout -b hotfix/1.3.1
git commit -m "Fixed security vulnerability"
git push --set-upstream origin hotfix/1.3.1

📌 Expected Version:

1.3.1-hotfix.1

📌 NuGet Package Name:

MyLibrary.1.3.1-hotfix.1.nupkg

✅ Best Practices:

• Always branch from main for hotfixes.
• Merge back into main after testing.

---

8️⃣ Handling Chores (No Version Change)

💡 Goal: Make internal changes (e.g., documentation, CI/CD).

🔹 How to Do It:

git commit -m "+semver: none Updated README.md"
git push

📌 Expected Version:

1.3.0-alpha.3 (unchanged)

✅ Best Practices:

• Use +semver: none to skip version bumps.

---

9️⃣ Pull Request Strategy

💡 Goal: Merge a feature branch into develop.

🔹 PR Title Guidelines:

Change Type	Example PR Title
Feature	feat: Added new analytics API
Bug Fix	fix: Resolved null reference exception
Refactor	refactor: Optimized database queries
Chore	chore: Updated build pipeline

---

🚀 Final Summary

Goal	Branch	Git Action	Expected Version
Development Build	develop	git commit -m "New feature"	1.2.3-alpha.N
Feature Work	feature/*	git commit -m "Feature added"	1.2.3-feature.BranchName.N
Minor Release	develop	+semver: minor	1.3.0-alpha.1
Major Release	develop	+semver: major	2.0.0-alpha.1
Release Candidate	release/*	git checkout -b release/X.Y.Z	1.3.0-beta.1
Stable Release	main	git tag vX.Y.Z	1.3.0
Hotfix	hotfix/*	git checkout -b hotfix/X.Y.Z	1.3.1-hotfix.1
Chores	any	+semver: none	No change

---

🚀 Follow this cookbook to ensure correct versioning and smooth GitVersion integration in your .NET projects! 🚀