[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

1 files changed, 85 insertions, 0 deletions

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)