[Feature] Group configuration under calculation and output sections with migration support

[arturcic]

Summary

Restructure GitVersion configuration into calculation and output sections, add POSIX migration tooling, and provide a one-release fallback for the legacy flat configuration.

This umbrella is implemented through #5132, #5133, and #5134. The cross-feature release matrix and selector lifecycle are governed by #5135.

Progress

• Implement versioned calculation and output configuration #5132 — Implement versioned calculation and output configuration (merged in Implement versioned calculation and output configuration #5158).
• Add POSIX configuration migration and legacy-format warnings #5133 — Add configuration migration and legacy-format warnings (merged in Add POSIX configuration migration and legacy-format warnings #5159).
• Publish v7 configuration schemas and migration guidance #5134 — Publish configuration schemas and migration guidance (merged in Document v7 configuration layout and migration #5160).
• Configuration foundation completed by Implement versioned calculation and output configuration #5158, Add POSIX configuration migration and legacy-format warnings #5159 and Document v7 configuration layout and migration #5160.

Follow-up release work is outside this completed umbrella: #5135 owns v7.0 selector/default alignment; #5188 owns v7.1 parser/configuration runtime removal; #5040 owns v7.1 backend removal; #5136 owns v8 selector removal.

Proposed structure

workflow: GitFlow/v1
calculation:
  tag-prefix: '[vV]?'
  semantic-version-format: Strict
  strategies: [ConfiguredNextVersion, MergeMessage, TaggedCommit]
  ignore:
    sha: []
    paths: []
  branches:
    main:
      regex: ^master$|^main$
      mode: ContinuousDelivery
      label: ''
      increment: Patch

output:
  assembly-versioning-scheme: MajorMinorPatch
  assembly-file-versioning-scheme: MajorMinorPatch
  assembly-informational-format: '{InformationalVersion}'
  commit-date-format: yyyy-MM-dd
  tag-pre-release-weight: 60000
  update-build-number: true
  branches:
    main:
      custom-version-format: '{SemVer}'
      pre-release-weight: 55000

Setting ownership

workflow is a root-level preset selector for the whole configuration. Templates supply defaults to both calculation and output; user configuration overrides the preset, and runtime overrides take precedence. A workflow-only document is valid in both v6 and v7.

calculation contains semantic-version and Git-history inputs:

• next-version, tag-prefix, and version-in-branch-pattern
• version-bump and no-bump message patterns
• merge-message-formats, semantic-version-format, strategies, and ignore
• calculation branch defaults and calculation.branches: mode, label, increment, prevent-increment, merge tracking, commit-message incrementing, regex/source relationships, and branch classification

label remains a calculation setting because it changes SemVer and FullSemVer.

output contains generated-variable and output-integration settings:

• assembly versioning schemes and formats
• assembly-informational-format, commit-date-format, tag-pre-release-weight, and update-build-number
• output branch defaults and output.branches: custom-version-format and pre-release-weight

Calculation and output entries for the same branch are merged logically. Output configuration may target a branch supplied by a built-in workflow without repeating its calculation configuration.

Configuration model and validation

• Represent both sections explicitly in the configuration model.
• Resolve v6 and v7 representations to equivalent effective runtime configuration during v7.0.
• Reject documents mixing flat and nested settings.
• Keep calculation consumers independent of output-only settings where practical.
• Update built-in workflows, builders, inheritance, serialization, --show-config, overrides, caching, schemas, and public API baselines.

POSIX migration command

Add to the stable System.CommandLine parser:

gitversion config migrate
gitversion config migrate --config GitVersion.yml
gitversion config migrate --config GitVersion.yml --output GitVersion.v7.yml
gitversion config migrate --config GitVersion.yml --in-place

• Default input uses normal configuration discovery and default output is stdout.
• --output refuses overwrite without --force; --in-place explicitly replaces the input; both are mutually exclusive.
• Migration is deterministic and idempotent and preserves all configured values.
• Warn before in-place migration if comments cannot be preserved.
• Explicit input does not require repository discovery or normalization.
• The command exists only in the stable POSIX parser, not LegacyArgumentParser or experimental new-cli.
• A positional directory named config uses the unambiguous --target-path config form.

Follow-up release matrix (tracked separately)

Use GITVERSION_CONFIGURATION_VERSION=v6|v7 as specified by #5135:

• v7.0 defaults to nested v7 configuration; v6 is an explicit temporary fallback.
• v7.1 removes runtime support for flat v6 configuration. v6 produces an actionable error directing users to gitversion config migrate.
• Explicit v7 remains accepted as a no-op throughout v7.x.
• Remove feature-selector environment variables #5136 removes the selector entirely in v8.

--show-config emits the selected format. In v7 mode, --override-config uses nested paths and rejects legacy paths with replacement guidance; v6 mode does the inverse.

Acceptance criteria

• Every current setting has an explicit calculation or output destination.
• custom-version-format and pre-release-weight work as output defaults and under output.branches.
• v6 and v7 configurations have calculation/output parity in v7.0.
• Nested v7 configuration and explicit v6 fallback are implemented; explicit v6 user-file loading warns. Cross-feature v7.0 default alignment is tracked by v7.0: default to v7 parser, nested configuration and managed Git #5135.
• v7.1 runtime removal is outside this completed scope and tracked by v7.1: remove legacy argument parser and v6 configuration runtime #5188; migration tooling remains available.
• Migration, overrides, workflows, --show-config, caching, serialization, schemas, docs, and public APIs are tested and updated.

[arturcic]

@asbjornu @HHobeck please have a look and tell me what do you think

[arturcic]

Version-aware override validation

--override-config must validate keys against the configuration version selected for the process before applying any override:

• In v7 mode, reject legacy flat paths instead of accepting, translating, or silently ignoring them. The error should identify the legacy path and its nested replacement when one is known. For example: Override 'tag-prefix' uses a legacy v6 configuration path. Use 'calculation.tag-prefix' in v7 mode.
• In v6 mode, reject nested v7 paths with the corresponding legacy-path suggestion when one exists.
• Do not automatically translate override paths at runtime. Automatic translation could conceal a stale script after the compatibility parser is removed.
• Apply the same rule to repeated --override-config arguments: if any key belongs to the wrong configuration version, fail the invocation before calculation.
• Include branch-aware mappings. For example, a calculation override belongs under calculation.branches.<name>, while custom-version-format and pre-release-weight belong under output.branches.<name>.
• Error messages should mention gitversion config migrate for users who also need to migrate their configuration file.

Legacy-configuration deprecation warning

Warn users at runtime when GitVersion loads a user-provided legacy flat configuration:

• In v7.0, emit one warning per invocation when a discovered or explicitly selected user configuration contains legacy settings. Explain that the default changes to the nested v7 format in v7.1, show gitversion config migrate, and mention GITVERSION_CONFIGURATION_VERSION=v7 for validating the migrated file.
• In v7.1, emit the warning whenever the explicit v6 compatibility mode is used with a legacy user configuration.
• Do not warn when no user configuration file exists and GitVersion is only using built-in defaults.
• Do not emit the deprecation warning from config migrate, because reading legacy configuration is the purpose of that command.
• Send the warning through the diagnostic/logging channel, not machine-readable JSON, YAML, or single-variable stdout.
• The warning is advisory and must not change the exit code.
• Include the configuration file path in the warning when available.

Suggested warning:

The legacy flat GitVersion configuration in '<path>' is deprecated. The nested v7 configuration becomes the default in GitVersion 7.1. Run 'gitversion config migrate --config <path>' and validate it with GITVERSION_CONFIGURATION_VERSION=v7.

Additional acceptance criteria:

• Tests verify that v7 mode rejects legacy override paths with the correct nested-path suggestion.
• Tests verify that v6 mode rejects nested override paths with the correct legacy-path suggestion.
• Tests verify that invalid paths fail before configuration merging or version calculation.
• Tests verify warning presence, content, file path, once-per-invocation behavior, stdout isolation, and the no-user-config and migration-command exceptions.

[arturcic]

@asbjornu @HHobeck I need your opinion on this changes