Expose VersionSourceSemVer as Output Variable

[jakublatkowski]

This PR adds VersionSourceSemVer to the standard output variables exposed by GitVersion.

Description

This PR adds VersionSourceSemVer to the standard output variables exposed by GitVersion, making it available alongside existing version fields in:

• Environment variables (e.g., GitVersion_VersionSourceSemVer)
• JSON output
• Build agent-specific outputs (Azure Pipelines, GitHub Actions, etc.)

The VersionSourceSemVer represents the base semantic version calculated by GitVersion before any pre-release tags or metadata are applied. This is the foundational version derived from the repository's version tags and configuration.

Related Issue

This PR addresses a feature request for exposing VersionSourceSemVer in output variables.
Resolves #4803

Motivation and Context

The Problem

GitVersion determines the version by identifying a "Base Version" (from a tag, merge message, or branch config) and then incrementally applying rules to calculate the new version. While we currently expose the distance from this base (via CommitsSinceVersionSource), the BaseVersion itself is internal. Users verify this "anchor" point only by reading verbose logs, making it difficult to debug why a specific version was calculated or to perform logic based on the version calculation's starting point.

Why VersionSourceSemVer Matters

• Traceability & Debugging: It allows consumers to see exactly which version GitVersion selected as the anchor. This confirms whether the version is derived from the expected tag 1.0.0 or unexpectedly from a merge commit or branch configuration.
  Workflow Flexibility: In strict tag-based workflows (like GitFlow), VersionSourceSemVer often correlates to the "previous release," enabling scripts to generate diffs or changelogs from that point.
• Consistency: It provides the missing "start" value to the existing "end" value (FullSemVer) and "distance" value (CommitsSinceVersionSource), completing the version calculation picture for CI/CD integrations.

Note: Since GitVersion supports multiple strategies (e.g., specific branch naming), VersionSourceSemVer represents the calculation baseline found by the strategy, which is not strictly always the historically previous release, but it is always the deterministic anchor for the current build.

Why This Change is Valuable

By exposing VersionSourceSemVer as a standard output variable, we:

• Eliminate workarounds: Teams no longer need custom parsing logic
• Improve consistency: All version components are available through the same interface
• Enable new integrations: Simplifies integration with tools that need base version information
• Follow principle of least surprise: If GitVersion calculates it, users should be able to access it

How Has This Been Tested?

Unit Tests: Added/updated tests to verify:

• VersionSourceSemVer is included in output variable collections
• Value is correctly propagated to all output channels
• Backward compatibility with existing outputs

Verification Steps

• Confirmed VersionSourceSemVer appears in all output formats
• Verified value matches the internally calculated base version
• Checked that existing output variables remain unchanged
• Tested with different GitVersion configuration scenarios

Screenshots (if appropriate):

Example JSON output showing the new VersionSourceSemVer field:

{
  "Major": 5,
  "Minor": 12,
  "Patch": 0,
  "SemVer": "5.12.0-beta.1",
  "FullSemVer": "5.12.0-beta.1+42",
  ...
  "VersionSourceSemVer": "5.12.0",
  ...
}

Additional Notes

This change is purely additive - it introduces a new output variable without modifying any existing behavior or outputs. The risk of regression is minimal, and it opens up new integration possibilities for teams using GitVersion in their CI/CD pipelines.

Checklist:

• My code follows the code style of this project.
• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• I have added tests to cover my changes.
• All new and existing tests passed.

[HHobeck]

I think you need to update the following source in docs/input/docs/reference/variable.md.

See: https://gitversion.net/docs/reference/variables

[arturcic]

@jakublatkowski please make sure you rebase your branch onto main and not merge main into your branch

[Copilot]

Pull request overview

This PR exposes the VersionSourceSemVer variable as a standard output variable, making it available alongside existing version fields in environment variables, JSON output, and build agent-specific outputs. The VersionSourceSemVer represents the base semantic version calculated by GitVersion before any pre-release tags or metadata are applied.

Changes:

• Added VersionSourceSemVer property to core data model classes (SemanticVersionBuildMetaData, SemanticVersionFormatValues, GitVersionVariables)
• Updated version calculators to pass base version information instead of just commit references
• Modified deployment mode calculator interface to accept IBaseVersion instead of ICommit?
• Updated all test files and approved test outputs to include the new variable

Reviewed changes

Copilot reviewed 42 out of 42 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/GitVersion.Core/SemVer/SemanticVersionBuildMetaData.cs	Added VersionSourceSemVer property and updated constructor signature to accept it as first parameter
src/GitVersion.Core/VersionCalculation/SemanticVersioning/SemanticVersionFormatValues.cs	Added property to expose VersionSourceSemVer as string
src/GitVersion.Core/OutputVariables/GitVersionVariables.cs	Added VersionSourceSemVer to the output variables record
src/GitVersion.Core/VersionCalculation/VariableProvider.cs	Updated to pass VersionSourceSemVer when creating variables
src/GitVersion.Core/VersionCalculation/VersionCalculators/VersionCalculatorBase.cs	Modified to accept IBaseVersion and extract semantic version from it
src/GitVersion.Core/VersionCalculation/VersionCalculators/*.cs	Updated deployment mode calculators to use new IBaseVersion parameter
src/GitVersion.Core/VersionCalculation/Abstractions/IDeploymentModeCalculator.cs	Changed interface to accept IBaseVersion instead of ICommit?
src/GitVersion.Core/PublicAPI.*.txt	Documented breaking changes and new public API members
src/GitVersion.Output/Serializer/VersionVariablesJsonModel.cs	Added VersionSourceSemVer to JSON output model
src/GitVersion.MsBuild/Tasks/GetVersion.cs	Added VersionSourceSemVer output property to MSBuild task
src/GitVersion.MsBuild/PublicAPI.Unshipped.txt	Documented new MSBuild task property
src/GitVersion.*.Tests/**/*.cs	Updated all test files to use new constructor signature
src/GitVersion.*.Tests/**/Approved/*.txt	Updated all approved test outputs to include new variable
docs/input/docs/reference/variables.md	Added documentation for the new variable

[sonarqubecloud]

Quality Gate passed

Issues
3 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud