[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, 91 insertions, 44 deletions

diff --git a/toolsrc/src/vcpkg-test/dependencies.cpp b/toolsrc/src/vcpkg-test/dependencies.cpp
index 2831ea5a1..8f936abc3 100644
--- a/toolsrc/src/vcpkg-test/dependencies.cpp
+++ b/toolsrc/src/vcpkg-test/dependencies.cpp
@@ -196,7 +196,7 @@ private:
 
 static const MockOverlayProvider s_empty_mock_overlay;
 
-ExpectedS<Dependencies::ActionPlan> create_versioned_install_plan(
+static ExpectedS<Dependencies::ActionPlan> create_versioned_install_plan(
     const PortFileProvider::IVersionedPortfileProvider& provider,
     const PortFileProvider::IBaselineProvider& bprovider,
     const CMakeVars::CMakeVarProvider& var_provider,
@@ -335,7 +335,7 @@ TEST_CASE ("basic version install scheme baseline missing success", "[versionpla
                                              bp,
                                              var_provider,
                                              {
-                                                 Dependency{"a", {}, {}, {Constraint::Type::Exact, "2"}},
+                                                 Dependency{"a", {}, {}, {Constraint::Type::Minimum, "2"}},
                                              },
                                              {},
                                              toplevel_spec()));
@@ -375,7 +375,7 @@ TEST_CASE ("version string baseline agree", "[versionplan]")
     MockCMakeVarProvider var_provider;
 
     auto install_plan = create_versioned_install_plan(
-        vp, bp, var_provider, {Dependency{"a", {}, {}, {Constraint::Type::Exact, "2"}}}, {}, toplevel_spec());
+        vp, bp, var_provider, {Dependency{"a", {}, {}, {Constraint::Type::Minimum, "2"}}}, {}, toplevel_spec());
 
     REQUIRE(install_plan.has_value());
 }
@@ -396,7 +396,7 @@ TEST_CASE ("version install scheme baseline conflict", "[versionplan]")
                                                       bp,
                                                       var_provider,
                                                       {
-                                                          Dependency{"a", {}, {}, {Constraint::Type::Exact, "3"}},
+                                                          Dependency{"a", {}, {}, {Constraint::Type::Minimum, "3"}},
                                                       },
                                                       {},
                                                       toplevel_spec());
@@ -421,7 +421,7 @@ TEST_CASE ("version install string port version", "[versionplan]")
                                              bp,
                                              var_provider,
                                              {
-                                                 Dependency{"a", {}, {}, {Constraint::Type::Exact, "2", 1}},
+                                                 Dependency{"a", {}, {}, {Constraint::Type::Minimum, "2", 1}},
                                              },
                                              {},
                                              toplevel_spec()));
@@ -447,7 +447,7 @@ TEST_CASE ("version install string port version 2", "[versionplan]")
                                              bp,
                                              var_provider,
                                              {
-                                                 Dependency{"a", {}, {}, {Constraint::Type::Exact, "2", 0}},
+                                                 Dependency{"a", {}, {}, {Constraint::Type::Minimum, "2", 0}},
                                              },
                                              {},
                                              toplevel_spec()));
@@ -463,10 +463,10 @@ TEST_CASE ("version install transitive string", "[versionplan]")
 
     MockVersionedPortfileProvider vp;
     vp.emplace("a", {"2", 0}).source_control_file->core_paragraph->dependencies = {
-        Dependency{"b", {}, {}, DependencyConstraint{Constraint::Type::Exact, "1"}},
+        Dependency{"b", {}, {}, DependencyConstraint{Constraint::Type::Minimum, "1"}},
     };
     vp.emplace("a", {"2", 1}).source_control_file->core_paragraph->dependencies = {
-        Dependency{"b", {}, {}, DependencyConstraint{Constraint::Type::Exact, "2"}},
+        Dependency{"b", {}, {}, DependencyConstraint{Constraint::Type::Minimum, "2"}},
     };
     vp.emplace("b", {"1", 0});
     vp.emplace("b", {"2", 0});
@@ -478,7 +478,7 @@ TEST_CASE ("version install transitive string", "[versionplan]")
                                              bp,
                                              var_provider,
                                              {
-                                                 Dependency{"a", {}, {}, {Constraint::Type::Exact, "2", 1}},
+                                                 Dependency{"a", {}, {}, {Constraint::Type::Minimum, "2", 1}},
                                              },
                                              {},
                                              toplevel_spec()));
@@ -1006,7 +1006,7 @@ TEST_CASE ("version install scheme change in port version", "[versionplan]")
 {
     MockVersionedPortfileProvider vp;
     vp.emplace("a", {"2", 0}).source_control_file->core_paragraph->dependencies = {
-        Dependency{"b", {}, {}, DependencyConstraint{Constraint::Type::Exact, "1"}},
+        Dependency{"b", {}, {}, DependencyConstraint{Constraint::Type::Minimum, "1"}},
     };
     vp.emplace("a", {"2", 1}).source_control_file->core_paragraph->dependencies = {
         Dependency{"b", {}, {}, DependencyConstraint{Constraint::Type::Minimum, "1", 1}},
@@ -1026,7 +1026,7 @@ TEST_CASE ("version install scheme change in port version", "[versionplan]")
                                                  bp,
                                                  var_provider,
                                                  {
-                                                     Dependency{"a", {}, {}, {Constraint::Type::Exact, "2", 1}},
+                                                     Dependency{"a", {}, {}, {Constraint::Type::Minimum, "2", 1}},
                                                  },
                                                  {},
                                                  toplevel_spec()));
@@ -1045,7 +1045,7 @@ TEST_CASE ("version install scheme change in port version", "[versionplan]")
                                                  bp,
                                                  var_provider,
                                                  {
-                                                     Dependency{"a", {}, {}, {Constraint::Type::Exact, "2", 0}},
+                                                     Dependency{"a", {}, {}, {Constraint::Type::Minimum, "2", 0}},
                                                  },
                                                  {},
                                                  toplevel_spec()));
@@ -1305,7 +1305,8 @@ TEST_CASE ("version install transitive overrides", "[versionplan]")
     MockVersionedPortfileProvider vp;
 
     vp.emplace("b", {"1", 0}, Scheme::Relaxed)
-        .source_control_file->core_paragraph->dependencies.push_back({"c", {}, {}, {Constraint::Type::Exact, "2", 1}});
+        .source_control_file->core_paragraph->dependencies.push_back(
+            {"c", {}, {}, {Constraint::Type::Minimum, "2", 1}});
     vp.emplace("b", {"2", 0}, Scheme::Relaxed);
     vp.emplace("c", {"1", 0}, Scheme::String);
     vp.emplace("c", {"2", 1}, Scheme::String);
diff --git a/toolsrc/src/vcpkg-test/manifests.cpp b/toolsrc/src/vcpkg-test/manifests.cpp
index 39e470075..0af9f4f96 100644
--- a/toolsrc/src/vcpkg-test/manifests.cpp
+++ b/toolsrc/src/vcpkg-test/manifests.cpp
@@ -62,6 +62,7 @@ TEST_CASE ("manifest construct minimum", "[manifests]")
     REQUIRE(pgh.core_paragraph->maintainers.empty());
     REQUIRE(pgh.core_paragraph->description.empty());
     REQUIRE(pgh.core_paragraph->dependencies.empty());
+    REQUIRE(!pgh.core_paragraph->builtin_baseline.has_value());
 
     REQUIRE(!pgh.check_against_feature_flags({}, feature_flags_without_versioning));
 }
@@ -157,19 +158,31 @@ TEST_CASE ("manifest versioning", "[manifests]")
     }
 }
 
-TEST_CASE ("manifest constraints error hash", "[manifests]")
+TEST_CASE ("manifest constraints hash", "[manifests]")
 {
+    auto p = unwrap(test_parse_manifest(R"json({
+    "name": "zlib",
+    "version-string": "abcd",
+    "dependencies": [
+        {
+            "name": "d",
+            "version>=": "2018-09-01#1"
+        }
+    ]
+})json"));
+    REQUIRE(p->core_paragraph->dependencies.at(0).constraint.value == "2018-09-01");
+    REQUIRE(p->core_paragraph->dependencies.at(0).constraint.port_version == 1);
+
     test_parse_manifest(R"json({
     "name": "zlib",
     "version-string": "abcd",
     "dependencies": [
         {
-            "name": "b",
-            "version=": "5#1"
+            "name": "d",
+            "version>=": "2018-09-01#0"
         }
     ]
-}
-)json",
+})json",
                         true);
 
     test_parse_manifest(R"json({
@@ -178,7 +191,20 @@ TEST_CASE ("manifest constraints error hash", "[manifests]")
     "dependencies": [
         {
             "name": "d",
-            "version>=": "2018-09-01#1"
+            "version>=": "2018-09-01#-1"
+        }
+    ]
+})json",
+                        true);
+
+    test_parse_manifest(R"json({
+    "name": "zlib",
+    "version-string": "abcd",
+    "dependencies": [
+        {
+            "name": "d",
+            "version>=": "2018-09-01",
+            "port-version": 1
         }
     ]
 })json",
@@ -238,14 +264,10 @@ TEST_CASE ("manifest constraints", "[manifests]")
     std::string raw = R"json({
     "name": "zlib",
     "version-string": "abcd",
+    "builtin-baseline": "089fa4de7dca22c67dcab631f618d5cd0697c8d4",
     "dependencies": [
         "a",
         {
-            "name": "b",
-            "port-version": 12,
-            "version=": "5"
-        },
-        {
             "$extra": null,
             "name": "c"
         },
@@ -263,32 +285,17 @@ TEST_CASE ("manifest constraints", "[manifests]")
     REQUIRE(pgh.check_against_feature_flags({}, feature_flags_without_versioning));
     REQUIRE(!pgh.check_against_feature_flags({}, feature_flags_with_versioning));
     REQUIRE(Json::stringify(serialize_manifest(pgh), Json::JsonStyle::with_spaces(4)) == raw);
-    REQUIRE(pgh.core_paragraph->dependencies.size() == 4);
+    REQUIRE(pgh.core_paragraph->dependencies.size() == 3);
     REQUIRE(pgh.core_paragraph->dependencies[0].name == "a");
     REQUIRE(pgh.core_paragraph->dependencies[0].constraint ==
             DependencyConstraint{Versions::Constraint::Type::None, "", 0});
-    REQUIRE(pgh.core_paragraph->dependencies[1].name == "b");
+    REQUIRE(pgh.core_paragraph->dependencies[1].name == "c");
     REQUIRE(pgh.core_paragraph->dependencies[1].constraint ==
-            DependencyConstraint{Versions::Constraint::Type::Exact, "5", 12});
-    REQUIRE(pgh.core_paragraph->dependencies[2].name == "c");
-    REQUIRE(pgh.core_paragraph->dependencies[2].constraint ==
             DependencyConstraint{Versions::Constraint::Type::None, "", 0});
-    REQUIRE(pgh.core_paragraph->dependencies[3].name == "d");
-    REQUIRE(pgh.core_paragraph->dependencies[3].constraint ==
+    REQUIRE(pgh.core_paragraph->dependencies[2].name == "d");
+    REQUIRE(pgh.core_paragraph->dependencies[2].constraint ==
             DependencyConstraint{Versions::Constraint::Type::Minimum, "2018-09-01", 0});
-
-    test_parse_manifest(R"json({
-        "name": "zlib",
-        "version-string": "abcd",
-        "dependencies": [
-            {
-                "name": "d",
-                "version=": "2018-09-01",
-                "version>=": "2018-09-01"
-            }
-        ]
-    })json",
-                        true);
+    REQUIRE(pgh.core_paragraph->builtin_baseline == "089fa4de7dca22c67dcab631f618d5cd0697c8d4");
 
     test_parse_manifest(R"json({
         "name": "zlib",
@@ -303,6 +310,45 @@ TEST_CASE ("manifest constraints", "[manifests]")
                         true);
 }
 
+TEST_CASE ("manifest builtin-baseline", "[manifests]")
+{
+    SECTION ("valid baseline")
+    {
+        std::string raw = R"json({
+    "name": "zlib",
+    "version-string": "abcd",
+    "builtin-baseline": "089fa4de7dca22c67dcab631f618d5cd0697c8d4"
+}
+)json";
+        auto m_pgh = test_parse_manifest(raw);
+
+        REQUIRE(m_pgh.has_value());
+        auto& pgh = **m_pgh.get();
+        REQUIRE(pgh.check_against_feature_flags({}, feature_flags_without_versioning));
+        REQUIRE(!pgh.check_against_feature_flags({}, feature_flags_with_versioning));
+        REQUIRE(pgh.core_paragraph->builtin_baseline.value_or("does not have a value") ==
+                "089fa4de7dca22c67dcab631f618d5cd0697c8d4");
+    }
+
+    SECTION ("empty baseline")
+    {
+        std::string raw = R"json({
+    "name": "zlib",
+    "version-string": "abcd",
+    "builtin-baseline": ""
+}
+)json";
+
+        auto m_pgh = test_parse_manifest(raw);
+
+        REQUIRE(m_pgh.has_value());
+        auto& pgh = **m_pgh.get();
+        REQUIRE(pgh.check_against_feature_flags({}, feature_flags_without_versioning));
+        REQUIRE(!pgh.check_against_feature_flags({}, feature_flags_with_versioning));
+        REQUIRE(pgh.core_paragraph->builtin_baseline.value_or("does not have a value") == "");
+    }
+}
+
 TEST_CASE ("manifest overrides", "[manifests]")
 {
     std::tuple<StringLiteral, Versions::Scheme, StringLiteral> data[] = {