docs: document v7 configuration migration

Author: arturcic

BREAKING_CHANGES.md

@@ -55,6 +55,26 @@ The command-line interface has been migrated from Windows-style (`/switch` and s
 
 As a temporary migration aid, set the environment variable `GITVERSION_USE_V6_ARGUMENT_PARSER=true` to restore the legacy `/switch` and `-switch` argument handling. This escape hatch will be removed in a future release.
 
+### Configuration structure and migration
+
+v7 configuration now separates calculation from output:
+
+```yaml
+calculation:
+  branches:
+    main:
+      increment: Patch
+output:
+  update-build-number: true
+```
+
+v7.0 defaults to the nested layout. `GITVERSION_CONFIGURATION_VERSION=v6` is a
+temporary flat-layout fallback that logs a migration warning for user files.
+Convert files with `gitversion config migrate`. The command
+writes YAML to stdout by default, supports `--config`, `--output`,
+`--in-place`, and `--force`, and warns that comments cannot be preserved when
+replacing a file.
+
 #### Full argument mapping
 
 | Old argument                  | New argument                     | Short alias                    | Env var alternative          |

docs/input/docs/learn/branching-strategies/gitflow/examples.md

@@ -12,8 +12,9 @@ in GitVersion. To enable this workflow, the builtin template
 configuration as follows:
 
 ```yaml
-workflow: GitFlow/v1
-mode: ContinuousDelivery
+calculation:
+  mode: ContinuousDelivery
+  workflow: GitFlow/v1
 ```
 
 Where

docs/input/docs/learn/branching-strategies/githubflow/examples.md

@@ -10,8 +10,9 @@ in GitVersion. To enable this workflow, the builtin template
 configuration as follows:
 
 ```yaml
-workflow: GitHubFlow/v1
-mode: ContinuousDelivery
+calculation:
+  mode: ContinuousDelivery
+  workflow: GitHubFlow/v1
 ```
 
 Where

docs/input/docs/migration/v6-to-v7.md

@@ -117,6 +117,34 @@ gitversion --url https://github.com/org/repo.git --branch main --username user -
 
 For current command details and examples, see [CLI Arguments](/docs/usage/cli/arguments).
 
+## Configuration migration
+
+GitVersion v7 stores settings under `calculation` and `output`. Convert an
+existing flat v6 YAML document with the POSIX-only migration command:
+
+```shell
+gitversion config migrate
+gitversion config migrate --config GitVersion.yml --output GitVersion.v7.yml
+gitversion config migrate --config GitVersion.yml --in-place
+```
+
+The first command discovers `GitVersion.yml` and emits v7 YAML to stdout.
+`--output` requires `--force` to replace an existing file and cannot be used
+with `--in-place`. In-place migration warns because comments cannot be
+preserved. The command does not need a Git repository and migrating its v7
+output again is idempotent. In v7.0, you can temporarily validate a flat file
+with `GITVERSION_CONFIGURATION_VERSION=v6`; GitVersion warns once for that
+fallback.
+
+GitVersion 7 publishes a nested-only schema at
+`https://gitversion.net/schemas/7.0/GitVersion.configuration.json`. If you
+temporarily select `GITVERSION_CONFIGURATION_VERSION=v6`, keep the existing v6
+`$schema` reference (for example,
+`https://gitversion.net/schemas/6.3/GitVersion.configuration.json`) until you
+migrate. Do not point a flat document at the 7.0 schema. New v7 configuration
+settings require migrating to the nested layout with `gitversion config
+migrate` to retain schema validation.
+
 ## Git backend
 
 GitVersion v7 introduces a fully managed Git backend as an alternative to the native LibGit2Sharp (libgit2) implementation. The backend is selected with the `GITVERSION_GIT_BACKEND` environment variable. When the variable is not set (or empty), the release's default backend is used — you never need to set it. Setting it to any value other than `libgit2` or `managed` (case-insensitive) is an error: GitVersion fails fast instead of silently running the default backend with a typo unnoticed.
@@ -138,7 +166,8 @@ The environment variables relevant to migrating from v6 to v7:
 
 | Variable                            | Purpose                                                                                                             |
 | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
-| `GITVERSION_GIT_BACKEND`            | Selects the Git backend: `libgit2` (default in v7.0) or `managed`. See [Git backend](#git-backend).                 |
+| `GITVERSION_CONFIGURATION_VERSION`   | Selects the configuration layout: `v7` (default) or temporary flat `v6` fallback.                                   |
+| `GITVERSION_GIT_BACKEND`             | Selects the Git backend: `libgit2` (default in v7.0) or `managed`. See [Git backend](#git-backend).                 |
 | `GITVERSION_USE_V6_ARGUMENT_PARSER` | Set to `true` to temporarily restore the legacy v6 (`/switch`) argument parser. Removed in a future release.        |
 | `GITVERSION_REMOTE_USERNAME`        | Alternative to `--username` for dynamic-repository credentials.                                                     |
 | `GITVERSION_REMOTE_PASSWORD`        | Alternative to `--password` for dynamic-repository credentials.                                                     |

docs/input/docs/reference/build-servers/gitlab.md

@@ -29,11 +29,12 @@ After repository normalisation the friendly branch name becomes
 GitLab's namespace (the default `pull-requests|pull|pr` pattern does not):
 
 ```yaml
-workflow: GitFlow/v1
-branches:
-  pull-request:
-    regex: ^merge-requests/(?<Number>\d+)/(head|merge)$
-    label: PullRequest{Number}
+calculation:
+  branches:
+    pull-request:
+      label: PullRequest{Number}
+      regex: ^merge-requests/(?<Number>\d+)/(head|merge)$
+  workflow: GitFlow/v1
 ```
 
 `CI_COMMIT_REF_NAME` still contains the source branch name (for example