diff --git a/README.md b/README.md
index ec1fec7..1a9a45a 100644
--- a/README.md
+++ b/README.md
@@ -63,8 +63,8 @@ Defaults can be set per project or per folder via `Directory.Build.props` file.
```xml
- master:1;main:1;develop:2;release/*:3
- 0.0.12345.0
+ master:5;main:5;develop:4;release/*:3
+ 0.0.20000.0
```
diff --git a/docs/Versioning.md b/docs/Versioning.md
index e714531..648cb00 100644
--- a/docs/Versioning.md
+++ b/docs/Versioning.md
@@ -12,13 +12,13 @@ Git-based version number generation is enabled by default. The SDK automatically
|------|--------|---------|
| `Major` | First number from `` in your project file | `1` |
| `Minor` | Second number from `` in your project file | `0` |
-| `BranchPrefix` | Optional digit (0–5) from branch rules in `GitVersionNumberBranches` | `2` (for develop) |
+| `BranchPrefix` | Optional digit (0–5) from branch rules in `GitVersionNumberBranches` | `4` (for develop) |
| `YY` | Last two digits of the latest commit year | `26` |
| `MM` | Month of the latest commit (zero-padded) | `05` |
| `DD` | Day of the latest commit (zero-padded) | `15` |
| `CommitCount` | Number of commits on that day, zero-padded to 3 digits | `003` |
-**Example:** `Version=1.0`, branch `develop` (prefix `2`), latest commit on 2026-05-15 with 3 commits that day → **`1.0.22605.15003`**
+**Example:** `Version=1.0`, branch `develop` (prefix `4`), latest commit on 2026-05-15 with 3 commits that day → **`1.0.42605.15003`**
The branch prefix allows higher-priority branches (e.g. production) to always have a higher version than lower-priority branches, preventing accidental overwrites when deploying. Maximum prefix value is `5` due to the [build number limitation](https://learn.microsoft.com/en-us/archive/blogs/msbuild/why-are-build-numbers-limited-to-65535) in Windows.
@@ -29,16 +29,16 @@ Commit counts include commits from all referenced projects (resolved recursively
| Property | Default | Description |
|----------|---------|-------------|
| `GitVersionNumber` | `true` (SDK) / _empty_ (Tasks) | Master switch. Set to `false` to disable Git-based versioning entirely — the project's `Version` property is used as-is. When using the Tasks package directly (without the SDK), this is not set by default. |
-| `GitVersionNumberBranches` | `main:1;master:1;develop:2;` (SDK only) | Semicolon-separated branch rules. Each entry is `` or `:`. Wildcard patterns are supported (e.g. `feature/*:0`). Defaults are only applied when using the SDK package; the Tasks package alone does not populate this. |
-| `GitVersionNumberFallback` | `0.0.20000.0` | Version used when the current branch does not match any rule in `GitVersionNumberBranches`. |
+| `GitVersionNumberBranches` | `main:5;master:5;develop:4;` (SDK only) | Semicolon-separated branch rules. Each entry is `` or `:`. Wildcard patterns are supported (e.g. `release/*:3`). Defaults are only applied when using the SDK package; the Tasks package alone does not populate this. |
+| `GitVersionNumberFallback` | `0.0.20000.0` | Version used when the current branch does not match any rule in `GitVersionNumberBranches`. The `0.0` Major.Minor is intentional — it clearly marks the artifact as a local/untracked build and ensures the environment's version guard will reject it if any real CI artifact is already installed. |
These properties can be set per project in your `.csproj` or shared via `Directory.Build.props`:
```xml
- master:1;main:1;develop:2;release/*:3
- 0.0.12345.0
+ master:5;main:5;develop:4;release/*:3
+ 0.0.20000.0
```
diff --git a/src/Dataverse/Tasks/Tasks/GenerateGitVersion.cs b/src/Dataverse/Tasks/Tasks/GenerateGitVersion.cs
index 90ef04c..56d917a 100644
--- a/src/Dataverse/Tasks/Tasks/GenerateGitVersion.cs
+++ b/src/Dataverse/Tasks/Tasks/GenerateGitVersion.cs
@@ -41,6 +41,8 @@ public override bool Execute()
if (GitVersionNumberFallback == null)
{
Log.LogWarning("GitVersionNumberFallback is null, setting to default.");
+ // 0.0 Major.Minor intentionally marks this as a local/untracked build.
+ // The version guard on any real environment will reject it.
GitVersionNumberFallback = "0.0.20000.0";
}
diff --git a/src/Sdk/README.md b/src/Sdk/README.md
index 2104354..b403bf1 100644
--- a/src/Sdk/README.md
+++ b/src/Sdk/README.md
@@ -39,7 +39,7 @@ The `TALXISDevKitDataversePackageName` property can be set explicitly to overrid
| `TALXISDevKitDataversePackageVersion` | _(resolved from SDK install path)_ | Version used in the auto-generated package reference. Defaults to the installed SDK version, extracted from the NuGet cache path (`.../{id}/{version}/Sdk/Sdk.props`), so the referenced `TALXIS.DevKit.Build.Dataverse.*` package matches the SDK version. |
| `TALXISDevKitDataversePackageName` | `$(Base).$(ProjectType)` | Explicit package name; overrides the base + ProjectType combination. |
| `GitVersionNumber` | `true` | Enables Git-based version number generation. Set to `false` to opt out. See [Versioning](/docs/Versioning.md). |
-| `GitVersionNumberBranches` | `main:1;master:1;develop:2;` | Default branch rules for Git versioning. See [Versioning](/docs/Versioning.md). |
+| `GitVersionNumberBranches` | `main:5;master:5;develop:4;` | Default branch rules for Git versioning. See [Versioning](/docs/Versioning.md). |
## Related Packages
diff --git a/src/Sdk/Sdk/Sdk.targets b/src/Sdk/Sdk/Sdk.targets
index 9eefffd..0ca3da5 100644
--- a/src/Sdk/Sdk/Sdk.targets
+++ b/src/Sdk/Sdk/Sdk.targets
@@ -6,9 +6,18 @@
+ so that GitVersionNumber=false in the csproj correctly prevents population.
+
+ Priority ladder (higher prefix = higher version = wins on deployment):
+ develop : 4 (integration CI)
+ main/master : 5 (production – always wins)
+
+ Untracked/local builds fall back to 0.0.20000.0 — the 0.0 Major.Minor
+ is intentional: it makes local artifacts clearly distinguishable from CI
+ builds and prevents them from ever being imported over a real CI artifact
+ (the environment's version guard rejects any lower-version import). -->
- main:1;master:1;develop:2;
+ main:5;master:5;develop:4;