[docs] More Getting Started fixes (#18970)

* Use valid commmit ID for baseline

* More doc fixes

docs/examples/versioning.getting-started.md

@@ -20,11 +20,11 @@ Create a folder with the following files:
     "dependencies": [
         {
             "name": "fmt",
-            "version>=": "7.1.3"
+            "version>=": "7.1.3#1"
         }, 
         "zlib"
     ],
-    "builtin-baseline": "68a74950d0400f5a803026d0860f49853984bf11"
+    "builtin-baseline": "3426db05b996481ca31e95fff3734cf23e0f51bc"
 }
 ```
 
@@ -69,8 +69,10 @@ PS D:\versions-test\build> cmake -G Ninja -DCMAKE_TOOLCHAIN_FILE=D:/vcpkg/script
 -- Running vcpkg install
 Detecting compiler hash for triplet x86-windows...
 The following packages will be built and installed:
-    fmt[core]:x86-windows -> 7.1.3 -- D:\vcpkg\buildtrees\versioning\versions\fmt\dd8cf5e1a2dce2680189a0744102d4b0f1cfb8b6
-    zlib[core]:x86-windows -> 1.2.11#9 -- D:\vcpkg\buildtrees\versioning\versions\zlib\827111046e37c98153d9d82bb6fa4183b6d728e4
+    fmt[core]:x64-windows -> 7.1.3#1 -- D:\Work\viromer\vcpkg\buildtrees\versioning\versions\fmt\4f8427eb0bd40da1856d4e67bde39a4fda689d72
+    vcpkg-cmake[core]:x64-windows -> 2021-02-26 -- D:\Work\viromer\vcpkg\buildtrees\versioning\versions\vcpkg-cmake\51896aa8073adb5c8450daa423d03eedf0dfc61f
+    vcpkg-cmake-config[core]:x64-windows -> 2021-02-26 -- D:\Work\viromer\vcpkg\buildtrees\versioning\versions\vcpkg-cmake-config\d255b3d566a8861dcc99a958240463e678528066
+    zlib[core]:x64-windows -> 1.2.11#9 -- D:\Work\viromer\vcpkg\buildtrees\versioning\versions\zlib\827111046e37c98153d9d82bb6fa4183b6d728e4
 ...
 ```
 
@@ -90,7 +92,8 @@ zlib version is 1.2.11
 Take a look at the output:
 
 ```
-fmt[core]:x86-windows -> 7.1.3 -- D:\vcpkg\buildtrees\versioning\versions\fmt\dd8cf5e1a2dce2680189a0744102d4b0f1cfb8b6
+fmt[core]:x86-windows -> 7.1.3#1 -- D:\vcpkg\buildtrees\versioning\versions\fmt\4f8427eb0bd40da1856d4e67bde39a4fda689d72
+...
 zlib[core]:x86-windows -> 1.2.11#9 -- D:\vcpkg\buildtrees\versioning\versions\zlib\827111046e37c98153d9d82bb6fa4183b6d728e4
 ```
 
@@ -130,23 +133,23 @@ Version scheme   | Description
 }
 ```
 
-This property is used to express minimum version constraints, it is allowed only as part of the `"dependencies"` declarations. In our example we set an explicit constraint on version `7.1.3` of `fmt`. 
+This property is used to express minimum version constraints, it is allowed only as part of the `"dependencies"` declarations. In our example we set an explicit constraint on version `7.1.3#1` of `fmt`. 
 
 Vcpkg is allowed to upgrade this constraint if a transitive dependency requires a newer version. For example, if `zlib` were to declare a dependency on `fmt` version `7.1.4` then vcpkg would install `7.1.4` instead.
 
-Vcpkg uses a minimum version approach, in our example, even if `fmt` version `8.0.0` were to be released, vcpkg would still install version `7.1.3` as that is the minimum version that satisfies the constraint. The advantages of this approach are that you don't get unexpected dependency upgrades when you update vcpkg and you get reproducible builds (in terms of version used) as long as you use the same manifest. 
+Vcpkg uses a minimum version approach, in our example, even if `fmt` version `8.0.0` were to be released, vcpkg would still install version `7.1.3#1` as that is the minimum version that satisfies the constraint. The advantages of this approach are that you don't get unexpected dependency upgrades when you update vcpkg and you get reproducible builds (in terms of version used) as long as you use the same manifest. 
 
 If you want to upgrade your dependencies, you can bump the minimum version constraint or use a newer baseline.
 
 #### **`builtin-baseline`**
 
 ```json
-{ "builtin-baseline": "68a74950d0400f5a803026d0860f49853984bf11" }
+{ "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.
 
-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 `68a74950d0400f5a803026d0860f49853984bf11` to find out what version of `zlib` was the latest at that point in time (in our case it was `1.2.11#9`).
+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`).
 
 During version resolution, baseline versions are treated as minimum version constraints. If you declare an explicit constraint that is lower than a baseline version, the explicit constraint will be upgraded to the baseline version. 
 
@@ -155,7 +158,7 @@ For example, if we modified our dependencies like this:
 { "dependencies": [
     {
         "name": "fmt",
-        "version>=": "7.1.3"
+        "version>=": "7.1.3#1"
     },
     {
         "name": "zlib",
@@ -187,14 +190,14 @@ Let's modify our example once more, this time to force vcpkg to use version `6.0
     "dependencies": [
         {
             "name": "fmt",
-            "version>=": "7.1.3"
+            "version>=": "7.1.3#1"
         },
         {
             "name": "zlib",
             "version>=": "1.2.11#7"
         }
     ],
-    "builtin-baseline": "68a74950d0400f5a803026d0860f49853984bf11",
+    "builtin-baseline": "3426db05b996481ca31e95fff3734cf23e0f51bc",
     "overrides": [
         {
             "name": "fmt",

docs/users/versioning.md

@@ -31,7 +31,11 @@ Manifest property | Versioning scheme
 `version-date`    | For dates in the format YYYY-MM-DD
 `version-string`  | For arbitrary strings
 
-A manifest must contain only one version declaration.
+A manifest must contain only one version declaration. 
+
+_NOTE: By design, vcpkg does not compare versions that use different schemes. For example, a package
+that has a `version-string: 7.1.3` cannot be compared with the same package using `version: 7.1.4`, even if the
+conversion seems obvious._
 
 #### `version`
 Accepts version strings that follow a relaxed, dot-separated-, semver-like scheme.
@@ -111,13 +115,10 @@ 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.
 
-When resolving version constraints for a package, vcpkg will look for a baseline version:
-* First by looking at the baseline file in the given commit ID.
-* If the given commit ID does not contain a baseline file, vcpkg will fallback to use the local baseline file instead.
-* If there's no local baseline file, vcpkg will use the version currently available in the ports directory.
-
-_NOTE: If a baseline file is found, but it does not contain an entry for the package, the vcpkg invocation will fail._
-
+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.
 ### `version>=`
 Expresses a minimum version requirement, `version>=` declarations put a lower boundary on the versions that can be used to satisfy a dependency.
 
@@ -130,9 +131,9 @@ Example:
   "version-semver": "1.0.0",
   "dependencies": [
     { "name": "zlib", "version>=": "1.2.11#9" },
-    { "name": "fmt", "version>=": "7.1.3" }
+    { "name": "fmt", "version>=": "7.1.3#1" }
   ],
-  "builtin-baseline":"9fd3bd594f41afb8747e20f6ac9619f26f333cbe"
+  "builtin-baseline":"3426db05b996481ca31e95fff3734cf23e0f51bc"
 }
 ```
 
@@ -153,7 +154,7 @@ For an override to take effect, the overridden package must form part of the dep
     { "name": "zlib", "version>=": "1.2.11#9" },
     "fmt"
   ],
-  "builtin-baseline":"9fd3bd594f41afb8747e20f6ac9619f26f333cbe",
+  "builtin-baseline":"3426db05b996481ca31e95fff3734cf23e0f51bc",
   "overrides": [
     { "name": "fmt", "version": "6.0.0" }
   ]