[vcpkg] Add initial versioning documentation (#15565)

* [vcpkg] Improve efficiency and tests of versioning

* [vcpkg] Add initial versioning documentation and rename x-default-baseline to builtin-baseline

* [vcpkg] Enable metrics for builtin-baseline & overrides

* [vcpkg] Address PR comments

* [vcpkg] Add support for  syntax in version>=

* [vcpkg] Remove port-version from dependency syntax

* [vcpkg] Address CR comment

* [vcpkg] Minor docs fixup

2 files changed, 132 insertions, 3 deletions

diff --git a/docs/users/manifests.md b/docs/users/manifests.md
index 427d336c3..e1bc0c58b 100644
--- a/docs/users/manifests.md
+++ b/docs/users/manifests.md
@@ -64,6 +64,12 @@ Additionally, the `"port-version"` field is used by registries of packages,
 as a way to version "the package gotten from `vcpkg install`" differently from the upstream package version.
 You shouldn't need to worry about this at all.
 
+#### Additional version fields
+
+**Experimental behind the `versions` feature flag**
+
+See [versioning.md](versioning.md#version%20schemes) for additional version types.
+
 ### `"description"`
 
 This is where you describe your project. Give it a good description to help in searching for it!
@@ -71,6 +77,14 @@ This can be a single string, or it can be an array of strings;
 in the latter case, the first string is treated as a summary,
 while the remaining strings are treated as the full description.
 
+### `"builtin-baseline"`
+
+**Experimental behind the `versions` feature flag**
+
+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.
+
+See also [versioning](versioning.md#builtin-baseline) for more semantic details.
+
 ### `"dependencies"`
 
 This field lists all the dependencies you'll need to build your library (as well as any your dependents might need,
@@ -131,6 +145,16 @@ The common identifiers are:
 
 although one can define their own.
 
+#### `"version>="`
+
+**Experimental behind the `versions` feature flag**
+
+A minimum version constraint on the dependency.
+
+This field specifies the minimum version of the dependency using a '#' suffix to denote port-version if non-zero.
+
+See also [versioning](versioning.md#constraints) for more semantic details.
+
 #### Example:
 
 ```json
@@ -151,6 +175,26 @@ although one can define their own.
 }
 ```
 
+### `"overrides"`
+
+**Experimental behind the `versions` feature flag**
+
+This field enables version resolution to be ignored for certain dependencies and to use specific versions instead.
+
+See also [versioning](versioning.md#overrides) for more semantic details.
+
+#### Example:
+
+```json
+{
+  "overrides": [
+    {
+      "name": "arrow", "version": "1.2.3", "port-version": 7
+    }
+  ]
+}
+```
+
 ### `"supports"`
 
 If your project doesn't support common platforms, you can tell your users this with the `"supports"` field.
@@ -180,8 +224,9 @@ and that's the `"default-features"` field, which is an array of feature names.
   "name": "libdb",
   "description": [
     "An example database library.",
-    "Optionally uses one of CBOR, JSON, or CSV as a backend."
+    "Optionally can build with CBOR, JSON, or CSV as backends."
   ],
+  "$default-features-explanation": "Users using this library transitively will get all backends automatically",
   "default-features": [ "cbor", "csv", "json" ],
   "features": {
     "cbor": {
@@ -189,8 +234,7 @@ and that's the `"default-features"` field, which is an array of feature names.
       "dependencies": [
         {
           "$explanation": [
-            "This is currently how you tell vcpkg that the cbor feature depends on the json feature of this package",
-            "We're looking into making this easier"
+            "This is how you tell vcpkg that the cbor feature depends on the json feature of this package"
           ],
           "name": "libdb",
           "default-features": false,
diff --git a/docs/users/versioning.md b/docs/users/versioning.md
new file mode 100644
index 000000000..86840422b
--- /dev/null
+++ b/docs/users/versioning.md
@@ -0,0 +1,85 @@
+# Versioning
+
+**This feature is experimental and requires `--feature-flags=versions`**
+
+Versioning allows you to deterministically control the precise revisions of dependencies used by
+your project from within your manifest file.
+
+## Version schemes
+
+### Schemes
+Versions in vcpkg come in four primary flavors:
+
+#### version
+A dot-separated sequence of numbers (1.2.3.4)
+
+#### version-date
+A date (2021-01-01.5)
+
+#### version-semver
+A Semantic Version 2.0 (2.1.0-rc2)
+
+See https://semver.org/ for a full specification.
+
+#### version-string
+An exact, incomparable version (Vista)
+
+### Port Versions
+Each version additionally has a "port-version" which is a nonnegative integer. When rendered as text, the
+port version (if nonzero) is added as a suffix to the primary version text separated by a hash (#).
+Port-versions are sorted lexographically after the primary version text, for example:
+
+    1.0.0 < 1.0.0#1 < 1.0.1 < 1.0.1#5 < 2.0.0
+
+## Constraints
+
+Manifests can place three kinds of constraints upon the versions used:
+
+### builtin-baseline
+The baseline references a commit within the vcpkg repository that
+establishes a minimum version on every dependency in the graph. If
+no other constraints are specified (directly or transitively),
+then the version from the baseline of the top level manifest will
+be used.
+
+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.
+
+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>=`.
+
+### version>=
+Within the "dependencies" field, each dependency can have a
+minimum constraint listed. These minimum constraints will be used
+when transitively depending upon this library. A minimum
+port-version can additionally be specified with a '#' suffix.
+
+This constraint must refer to an existing, valid version (including port-version).
+
+### overrides
+When used as the top-level manifest (such as when running `vcpkg
+install` in the directory), overrides allow a manifest to
+short-circuit dependency resolution and specify exactly the
+version to use. These can be used to handle version conflicts,
+such as with `version-string` dependencies.
+
+Overrides are not considered from ports consumed as a dependency.
+
+## Example top-level manifest:
+```json
+{
+    "name": "example",
+    "version": "1.0",
+    "builtin-baseline": "a14a6bcb27287e3ec138dba1b948a0cdbc337a3a",
+    "dependencies": [
+        { "name": "zlib", "version>=": "1.2.11#8" },
+        "rapidjson"
+    ],
+    "overrides": [
+        { "name": "rapidjson", "version": "2020-09-14" }
+    ]
+}
+```
+See also the [manifest documentation](manifests.md) for more syntax information.
+
+## Original Specification
+
+See also the [original specification](https://github.com/vicroms/vcpkg/blob/versioning-spec/docs/specifications/versioning.md)