Add prerelease property to inheriting version.json files

[Copilot]

Allows inheriting version.json files to modify prerelease tags without duplicating version numbers. Eliminates sync errors when managing packages at different stability levels within the same repository.

Changes

Core Implementation

• Added Prerelease property to VersionOptions class with copy constructor and serialization support
• Implemented ApplyPrereleaseProperty method to apply prerelease transformations after parent-child merge
• Integrated prerelease application in all three version file implementations (base, managed, libgit2)

Schema & Validation

• Updated version.schema.json to restrict prerelease property to inheriting files only (inherit: true)
• Added pattern validation for prerelease values

Documentation

• Added "Prerelease Tag in Inheriting Files" section with usage rules and examples

Usage

Parent version.json:

{
  "version": "1.2"
}

Child version.json in subdirectory:

{
  "inherit": true,
  "prerelease": "beta"
}

Result: Child uses 1.2-beta while parent uses 1.2.

Behavior

• "prerelease": "beta" → Appends -beta to inherited version
• "prerelease": "" → Suppresses inherited prerelease tag
• Property omitted → Inherits prerelease tag unchanged

Tests

• Added 7 test methods covering all scenarios including multi-level inheritance and error cases

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• 3dovsblobprodeus2188.blob.core.windows.net
  • Triggering command: /opt/hostedtoolcache/dotnet/dotnet dotnet restore --no-dependencies /home/REDACTED/work/Nerdbank.GitVersioning/.codeql-scratch/dbs/csharp/working/32A0A2D38A721DD2A3E59F6279CF8961/missingpackages_workingdir --packages /home/REDACTED/work/Nerdbank.GitVersioning/.codeql-scratch/dbs/csharp/working/missingpackages /p:DisableImplicitNuGetFallbackFolder=true --verbosity normal --configfile /home/REDACTED/work/Nerdbank.GitVersioning/.codeql-scratch/dbs/csharp/working/nugetconfig/nuget.config --force (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Feature: Allow inheriting version.json to add unstable/prerelease suffix without duplicating version number</issue_title>
<issue_description>## Feature request: Inherit version number but allow unstable suffix in version.json

Currently, when using version.json inheritance in Nerdbank.GitVersioning, to publish an "unstable" prerelease from a stable branch (such as when one particular package is still considered unstable while its peers are already stable), the inherited version number must be hard-coded into both the original and the inheriting version.json. This can easily get out of sync and is error-prone.

Proposed feature:
Allow a version.json file to inherit the base version from an ancestor but append or override the 'prerelease' (unstable) portion without hard-coding the inherited version number. For example:

{
  "$schema": "https://raw.githubusercontent.com/dotnet/Nerdbank.GitVersioning/master/version.schema.json",
  "inherit": true,
  "prerelease": "beta"
}

or some similar property that enables the inheriting version.json to add/change only the prerelease suffix while continuing to inherit the numerics.

Motivation / scenario:

• Facilitate clean handling of release branches and dev branches without synchronized version updates in multiple files.
• Reduce maintenance friction and mistakes in version management workflows.

Desired outcome:

• A way to specify only a prerelease suffix in version.json that augments (does not override) an inherited version, without repeating or hardcoding the version numbers.
• The new prerelease property should be allowable only on version.json files that inherit, and which do not specify any prerelease suffix within their version property.
• Setting "prerelease": "" explicitly should have the effect of suppressing a prerelease suffix that might have been otherwise inherited. But merely omitting the prerelease property will have the effect of relying wholly on the version property (if specified) or inheriting whatever the parent version.json file specifies.
• New tests
• Updated documentation
• Updated version.schema.json. The schema should be written such that prerelease is only allowed when inherit: true is specified. Ideally it also forbids - appearing in the version property at the same time as the prerelease property appears, but only if that doesn't require cloning a huge chunk of schema which will be a maintenance burden.
  </issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes Feature: Allow inheriting version.json to add unstable/prerelease suffix without duplicating version number #1316

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.