[docs] Update docs with full release of manifests, registries, and ve…

…rsioning (microsoft#21929)

* [docs] Update docs with full release of manifests, registries, and versioning

* [docs] CR changes

docs/examples/modify-baseline-to-pin-old-boost.md

@@ -62,7 +62,7 @@ Use `"overrides"` to force specific versions in a package-by-package basis.
         { "name": "boost-core", "version": "1.72" },
         { "name": "boost-integer", "version": "1.72" },
         { "name": "boost-io", "version": "1.72" },
-        { "name": "boost-tuple", "version": "1.72" }     
+        { "name": "boost-tuple", "version": "1.72" }
     ]
 }
 ```
@@ -166,7 +166,7 @@ git checkout master
 
 In this example, commit SHA `9b5cf7c3d9376ddf43429671282972ec4f99aa85` is the commit ID with the modified baseline. Even when a different branch (`master` in this case) is checked out, Git is able to find the commit as long as the branch with the modified baseline exists (the `custom-boost-baseline` branch we created in step 1).
 
-We run `vcpkg --feature-flags="manifests,versions" install` in the directory containing our manifest file and the output looks like this:
+We run `vcpkg install` in the directory containing our manifest file and the output looks like this:
 
 ```
 The following packages will be built and installed:

docs/maintainers/registries.md

@@ -14,6 +14,7 @@ have created, please read [this documentation](../users/registries.md).
       - [Adding a New Version](#adding-a-new-version)
     - [Filesystem Registries](#filesystem-registries)
       - [Adding a New Version](#adding-a-new-version-1)
+    - [Builtin Registries](#builtin-registries)
 
 ## Overview
 
@@ -122,6 +123,13 @@ baseline to a commit ID, that commit ID must always exist, and be accessible
 from your HEAD commit, which is what is actually fetched. This means that your
 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.
+
 #### Adding a New Version
 
 There is some git trickery involved in creating a new version of a port. The

docs/users/manifests.md

@@ -74,21 +74,25 @@ This is a required field.
 
 ### Version fields
 
-There is, at this point, only one version field - `"version-string"`. However, more will be added in the future.
-You must have one (and only one) version field. There are different reasons to use each version field:
-
-* `"version-string"` - used for packages that don't have orderable versions. This is pretty uncommon,
-  but since we don't have any versioning constraints yet, this is the only one that you can use.
-
-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](versioning.md#version-schemes) for additional version types.
+There are four version field options, depending on how the port orders its
+releases.
+
+* [`"version"`](versioning.md#version) - Generic, dot-separated numeric
+  sequence.
+* [`"version-semver"`](versioning.md#version-semver) - [Semantic Version
+  2.0.0](https://semver.org/#semantic-versioning-specification-semver)
+* [`"version-date"`](versioning.md#version-date) - Used for packages which do
+  not have numeric releases (for example, Live-at-HEAD). Matches `YYYY-MM-DD`
+  with optional trailing dot-separated numeric sequence.
+* [`"version-string"`](versioning.md#version-string) - Used for packages that
+  don't have orderable versions. This should be rarely used, however all ports
+  created before the other version fields were introduced use this scheme.
+
+Additionally, the optional `"port-version"` field is used to indicate revisions
+to the port with the same upstream source version. For pure consumers, this
+field should not be used.
+
+See [versioning](versioning.md#version-schemes) for more details.
 
 ### `"description"`
 
@@ -99,11 +103,15 @@ 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.
 
-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.
+This is a convenience field that has the same semantic as replacing your default
+registry in
+[`vcpkg-configuration.json`](registries.md#configuration-default-registry).
 
-See also [versioning](versioning.md#builtin-baseline) for more semantic details.
+See [versioning](versioning.md#builtin-baseline) for more semantic details.
 
 ### `"dependencies"`
 
@@ -183,19 +191,18 @@ although one can define their own.
 
 #### `"version>="` Field
 
-**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.
+This field specifies the minimum version of the dependency, optionally using a
+`#N` suffix to denote port-version if non-zero.
 
 See also [versioning](versioning.md#version-1) for more semantic details.
 
 ### `"overrides"`
 
-**Experimental behind the `versions` feature flag**
+This field pins exact versions for individual dependencies.
 
-This field enables version resolution to be ignored for certain dependencies and to use specific versions instead.
+`"overrides"` from transitive manifests (i.e. from dependencies) are ignored.
 
 See also [versioning](versioning.md#overrides) for more semantic details.
 
@@ -275,8 +282,6 @@ and that's the `"default-features"` field, which is an array of feature names.
 
 ## Command Line Interface
 
-**Experimental behind the `manifests` feature flag**
-
 When invoked from any subdirectory of the directory containing `vcpkg.json`, `vcpkg install` with no package arguments
 will install all manifest dependencies into `<directory containing vcpkg.json>/vcpkg_installed/`. Most of `vcpkg
 install`'s classic mode parameters function the same in manifest mode.
@@ -458,7 +463,9 @@ not respond to changes unless a `.cpp` is edited.
 
 When using Visual Studio 2015 integration, these properties can be set in your project file before the
 
-    <Import Project="$(VCTargetsPath)\Microsoft.Cpp.props" />
+```xml
+<Import Project="$(VCTargetsPath)\Microsoft.Cpp.props" />
+```
 
 line, which unfortunately requires manual editing of the `.vcxproj` or passing on the msbuild command line with `/p:`.
 With 2017 or later integration, These properties can additionally be set via the Visual Studio GUI under

docs/users/registries.md

@@ -97,7 +97,7 @@ will work:
 {
   "default-registry": {
     "kind": "git",
-    "repository": "https://git.example.com/vcpkg",
+    "repository": "https://internal/mirror/of/github.com/Microsoft/vcpkg",
     "baseline": "eefee7408133f3a0fef711ef9c6a3677b7e06fd7"
   },
   "registries": [

docs/users/versioning.md

@@ -99,9 +99,14 @@ 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.
+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 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 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>=`.
 
 Example:
 ```json
@@ -113,12 +118,28 @@ 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.
+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 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>"
+  }
+}
+```
 
-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.
 
@@ -161,95 +182,6 @@ For an override to take effect, the overridden package must form part of the dep
 }
 ```
 
-## Version files
-Vcpkg uses a set of metadata files to power its versioning feature.
-
-These files are located in the following locations:
-* `${VCPKG_ROOT}/versions/baseline.json`, (this file is common to all ports) and
-* `${VCPKG_ROOT}/versions/${first-letter-of-portname}-/${portname}.json` (one per port).
-
-For example, for `zlib` the relevant files are:
-* `${VCPKG_ROOT}/versions/baseline.json`
-* `${VCPKG_ROOT}/versions/z-/zlib.json`
-
-The vcpkg public CI checks validate that each time a port is added or updated its respective version files are also updated.
-
-### Baseline file
-The baseline file located in `${VCPKG_ROOT}/versions/baseline.json` is used to declared the current baseline versions of all packages.
-
-For example:
-```json
-{
-  "default": {
-    "3fd": { "baseline": "2.6.3", "port-version": 0 },
-    "7zip": { "baseline": "19.00", "port-version": 2 },
-    "abseil": { "baseline": "2020-09-23", "port-version": 1 }
-  }
-}
-```
-
-Provided that there are no local modifications to the ports, the versions of all packages in the baseline file should map to the version of their corresponding portfiles in the `ports/` directory.
-
-### Versions file
-Each port in vcpkg has a corresponding versions file, the location of a port's versions file follows the pattern:
-
-```sh
-${VCPKG_ROOT}/versions/${first-letter-of-portname}-/${portname}.json
-```
-
-For example, for `zlib` the corresponding versions file is:
-
-```sh
-${VCPKG_ROOT}/versions/z-/zlib.json
-```
-
-These files contain an array of all the versions available for a given port.
-For example, the contents of `versions/z-/zlib.json` declare the following versions:
-```json
-{
-  "versions": [
-    {
-      "git-tree": "827111046e37c98153d9d82bb6fa4183b6d728e4",
-      "version-string": "1.2.11",
-      "port-version": 9
-    },
-    {
-      "git-tree": "068430e3e24fa228c302c808ba99f8a48d126557",
-      "version-string": "1.2.11",
-      "port-version": 8
-    },
-    ...
-  ]
-}
-```
-Each version declared in this file uses the same syntax used in manifest files, but adds an extra `git-tree` property. The value of `git-tree` is the SHA hash, as calculated by Git, of the directory containing the portfiles for the declared version. You can ask Git for the object SHA via the syntax:
-```
-git rev-parse <commit>:<path>
-```
-For example,
-```
-git rev-parse HEAD:ports/zlib
-```
-
-### Updating the version files
-The recommended method to update these files is to run the `x-add-version` command.
-
-For example, if you have made changes to `zlib`:
-
-```
-vcpkg x-add-version zlib
-```
-
-If you're updating multiple ports at the same time, instead you can run:
-
-```
-vcpkg x-add-version --all
-```
-
-To update the files for all modified ports at once.
-
-_NOTE: These commands require you to have committed your changes to the ports before running them. The reason is that the Git SHA of the port directory is required in these version files. But don't worry, the `x-add-version` command will warn you if you have local changes that haven't been committed._
-
 ## See Also
 
 * The [implementation details](versioning.implementation-details.md)