Add CustomVersion output variable

[arturcic]

Description

Adds a configurable CustomVersion output variable controlled by custom-version-format. The format supports the existing version-variable and environment-variable formatters and defaults to {SemVer} without changing the semantics of existing outputs.

The value is available in JSON output, generated version files, WiX output, and the MSBuild GetVersion task. Configuration, CLI override, output approvals, documentation, and generated schemas are updated as well.

Related Issue

Closes #1674
Closes #2065
Closes #3340
Closes #4659

Supersedes the implementation attempted in #4659 and follows the design described in discussion #4272.

Motivation and Context

Consumers sometimes need a version format with semantics different from GitVersion's standard outputs. Examples covered by this change include:

• PEP 440-compatible pre-release versions such as 0.6.3beta10.
• Fixed-width monotonically increasing integer versions for Android, such as 0001000.
• CI-owned build numbers supplied through environment variables.
• RPM/YUM-safe versions without dashes in the release value.

For #1674, separators in a branch-derived label can be removed with the PascalCase formatter:

custom-version-format: '{MajorMinorPatch}.{PreReleaseLabel:c}.{PreReleaseNumber}'

When the exact replacement must be controlled—for example, preserving JIRA.123 instead of reducing JIRA-123 to Jira123—replace {PreReleaseLabel:c} with an environment variable containing the desired RPM-safe label:

custom-version-format: '{MajorMinorPatch}.{env:RPM_PRERELEASE_LABEL}.{PreReleaseNumber}'

How Has This Been Tested?

• dotnet build ./src/GitVersion.slnx --no-restore
• dotnet test --project ./src/GitVersion.Configuration.Tests/GitVersion.Configuration.Tests.csproj --no-restore — 97 passed
• App parser override tests — 40 passed
• Relevant Core variable, JSON, and executor tests — 37 passed
• dotnet test --project ./src/GitVersion.Output.Tests/GitVersion.Output.Tests.csproj --no-restore — 123 passed
• dotnet test --project ./src/GitVersion.MsBuild.Tests/GitVersion.MsBuild.Tests.csproj --no-restore — 151 passed
• dotnet format ./src/GitVersion.slnx --verify-no-changes --no-restore
• Configuration and output schemas regenerated successfully

A broader Core test run reached an unrelated timing-sensitive failure in PerformanceScenarios.RepositoryWithALotOfTags (3518 ms versus the 2500 ms threshold); all CustomVersion-related tests pass.

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. See the performance-test note above.

[sonarqubecloud]

Quality Gate passed

Issues
0 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