[docs] Add documentation for x-update-baseline (#25256)

docs/commands/update-baseline.md

@@ -0,0 +1,42 @@
+# vcpkg x-update-baseline
+
+**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/commands/update-baseline.md).**
+
+**This command is experimental and may change or be removed at any time**
+
+## Synopsis
+
+```no-highlight
+vcpkg x-update-baseline [options] [--add-initial-baseline] [--dry-run]
+```
+
+## Description
+
+Update baselines for all configured [registries][].
+
+In [Manifest Mode][], this command operates on all [registries][] in the `vcpkg.json` and the [`vcpkg-configuration.json`][]. In Classic Mode, this command operates on the [`vcpkg-configuration.json`][] in the vcpkg instance (`$VCPKG_ROOT`).
+
+See the [versioning documentation](../users/versioning.md#baselines) for more information about baselines.
+
+## Options
+
+All vcpkg commands support a set of [common options](common-options.md).
+
+### `--dry-run`
+
+Print the planned baseline upgrades, but do not modify the files on disk.
+
+<a id="add-initial-baseline"></a>
+
+### `--add-initial-baseline`
+
+**[Manifest Mode][] Only**
+
+Add a [`"builtin-baseline"`][] field to the `vcpkg.json` if it does not already have one.
+
+Without this flag, it is an error to run this command on a manifest that does not have any [registries][] configured.
+
+[Manifest Mode]: ../users/manifests.md
+[`"builtin-baseline"`]: ../users/manifests.md#builtin-baseline
+[`vcpkg-configuration.json`]: ../users/registries.md#vcpkg-configurationjson
+[registries]: ../users/registries.md

docs/examples/versioning.getting-started.md

@@ -145,7 +145,7 @@ If you want to upgrade your dependencies, you can bump the minimum version const
 { "builtin-baseline": "3426db05b996481ca31e95fff3734cf23e0f51bc" }
 ```
 
-This field declares the versioning baseline for all ports. Setting a baseline is required to enable versioning, otherwise you will get the current versions on the ports directory. You can run 'git rev-parse HEAD' to get the current commit of vcpkg and set it as the builtin-baseline. See the [`builtin-baseline` documentation](../users/versioning.md#builtin-baseline) for more information.
+This field declares the versioning baseline for all ports. Setting a baseline is required to enable versioning, otherwise you will get the current versions on the ports directory. You can run 'git rev-parse HEAD' to get the current commit of vcpkg and set it as the builtin-baseline. See the [`builtin-baseline` documentation](../users/manifests.md#builtin-baseline) for more information.
 
 In our example, you can notice that we do not declare a version constraint for `zlib`; instead, the version is taken from the baseline. Internally, vcpkg will look in commit `3426db05b996481ca31e95fff3734cf23e0f51bc` to find out what version of `zlib` was the latest at that point in time (in our case it was `1.2.11#9`).
 

docs/maintainers/registries.md

@@ -125,10 +125,7 @@ HEAD commit should be a child of all previous HEAD commits.
 
 ### Builtin Registries
 
-Builtin registries are treated as special Git registries. Instead of fetching
-from a remote url, builtin registries consult the `$VCPKG_ROOT/.git` directory
-of the vcpkg clone. They use the currently checked out `$VCPKG_ROOT/versions`
-directory as the source for versioning information.
+Builtin registries are treated as special [Git registries](#git-registries). Instead of fetching from a remote url, builtin registries consult the `$VCPKG_ROOT/.git` directory of the vcpkg clone. They use the currently checked out `$VCPKG_ROOT/versions` directory as the source for versioning information.
 
 #### Adding a New Version
 
@@ -216,9 +213,7 @@ registries, which have the implicit versioning scheme of refs, filesystem
 registries can't rely on the version control system here. One possible option
 is to do a daily release, and have your "versions" be dates.
 
-_WARNING_: A baseline must always refer to the same set of versions. If you
-want to add new versions, you need to create a new version of the registry in
-the `baseline.json` file.
+_WARNING_: A baseline must not be modified once published. If you want to change or update versions, you need to create a new baseline in the `baseline.json` file.
 
 Here's an example of a valid `baseline.json`, for a registry that has decided
 upon dates for their versions:

docs/users/manifests.md

@@ -118,14 +118,19 @@ while the remaining strings are treated as the full description.
 ### `"builtin-baseline"`
 
 This field indicates the commit of vcpkg which provides global minimum version
-information for your manifest. It is required for top-level manifest files using
-versioning.
+information for your manifest.
 
-This is a convenience field that has the same semantic as replacing your default
-registry in
-[`vcpkg-configuration.json`](registries.md#configuration-default-registry).
+It is required for top-level manifest files using versioning without a specified [`"default-registry"`](registries.md#configuration-default-registry). It has the same semantic as defining your default registry to be:
+```json
+{
+  "default-registry": {
+    "kind": "builtin",
+    "baseline": "<value>"
+  }
+}
+```
 
-See [versioning](versioning.md#builtin-baseline) for more semantic details.
+See [versioning](versioning.md#baselines) for more semantic details.
 
 <a id="dependencies"></a>
 

docs/users/registries.md

@@ -52,9 +52,11 @@ The `"kind"` field must be a string:
 
 #### Registry Objects: `"baseline"`
 
-The `"baseline"` field must be a string. For git registries and for the 
-built-in registry, it should be a 40-character commit ID.
-For filesystem registries, it can be any string that the registry defines.
+The `"baseline"` field must be a string. It defines a minimum version for all packages coming from this registry configuration.
+
+For [Git Registries](../maintainers/registries.md#git-registries) and for the [Builtin Registry](../maintainers/registries.md#builtin-registries), it should be a 40-character git commit sha in the registry's repository that contains a `versions/baseline.json`.
+
+For [Filesystem Registries](../maintainers/registries.md#filesystem-registries), it can be any valid baseline string that the registry defines.
 
 #### Registry Objects: `"repository"`
 

docs/users/versioning.md

@@ -15,6 +15,8 @@ See our guide to [getting started with versioning](../examples/versioning.gettin
   * [`version-date`](#version-date)
   * [`version-string`](#version-string)
 * [Version constraints](#version-constraints)
+  * [Baselines](#baselines)
+  * [`version>=`](#version-gte)
 
 ## Version schemes
 Ports in vcpkg should attempt to follow the versioning conventions used by the package's authors. For that reason, when declaring a package's version the appropriate scheme should be used.
@@ -79,7 +81,7 @@ Examples:
 * `watermelon#0`< `watermelon#1`
 
 #### `port-version`
-A positive integer value that increases each time a vcpkg-specific change is made to the port.
+A positive integer value that increases each time the port changes without updating the sources.
 
 The rules for port versions are:
 * Start at 0 for the original version of the port,
@@ -97,17 +99,15 @@ Examples:
 
 ## Version constraints
 
-### `builtin-baseline`
-Accepts a Git commit ID. vcpkg will try to find a baseline file in the given
-commit ID and use that to set the baseline versions (lower bounds) of all
-dependencies.
+### Baselines
 
-Baselines provide stability and ease of development for top-level manifest
-files. They are not considered from ports consumed as a dependency. If a minimum
-version constraint is required during transitive version resolution, the port
-should use `version>=`.
+Baselines define a global version floor for what versions will be considered. This enables top-level manifests to keep the entire graph of dependencies up-to-date without needing to individually specify direct [`"version>="`][] constraints.
 
-Example:
+Every configured registry has an associated baseline. For manifests that don't configure any registries, the [`"builtin-baseline"`][] field defines the baseline for the built-in registry. If a manifest does not configure any registries and does not have a [`"builtin-baseline"`][], the install operates according to the Classic Mode algorithm and ignores all versioning information.
+
+Baselines, like other registry settings, are ignored from ports consumed as a dependency. If a minimum version is required during transitive version resolution the port should use [`"version>="`][].
+
+**Example**
 ```json
 {
   "name": "project",
@@ -117,27 +117,9 @@ Example:
 }
 ```
 
-You can get the current commit of your vcpkg instance either by adding an empty
-`"builtin-baseline"` field, installing, and examining the error message or by
-running `git rev-parse HEAD` in the root of the vcpkg instance.
+To add an initial `"builtin-baseline"`, use [`vcpkg x-update-baseline --add-initial-baseline`](../commands/update-baseline.md#add-initial-baseline). To update baselines in a manifest, use [`vcpkg x-update-baseline`](../commands/update-baseline.md).
 
-When resolving version constraints for a package, vcpkg will look for a baseline
-version by looking at the baseline file in the given commit ID. If the given
-commit ID doesn't have a `versions/baseline.json` file or if the baseline file
-exists but it does not declare a baseline version for the package the invocation
-will fail.
-
-This field is a convenience field that has the same semantic as replacing your
-default registry in
-[`vcpkg-configuration.json`](registries.md#configuration-default-registry).
-```json
-{
-  "default-registry": {
-    "kind": "builtin",
-    "baseline": "<baseline>"
-  }
-}
-```
+<a id="version-gte"></a>
 
 ### `version>=`
 Expresses a minimum version requirement, `version>=` declarations put a lower boundary on the versions that can be used to satisfy a dependency.
@@ -186,3 +168,5 @@ For an override to take effect, the overridden package must form part of the dep
 * The [implementation details](versioning.implementation-details.md)
 * The [original specification](../specifications/versioning.md)
 
+[`"version>="`]: #version-gte
+[`"builtin-baseilne"`]: manifests.md#builtin-baseline