[vcpkg] Add CI check for version files and update maintainer's guidel…

…ine (#15655)

* Add CI check using dummy version files

* Fix ci test

* Update maintainer's guideline

* Point CI check to actual version files

* Remove --git-verify-trees

* Fix typo

* Fix more typoes

* Even more typos

* Even more typos

docs/maintainers/maintainer-guide.md

@@ -204,6 +204,37 @@ For Example:
 
 See our [manifest files document](manifest-files.md#port-version) for a full explanation of our conventions.
 
+### Update the version files in `port_versions/` of any modified ports
+
+Vcpkg uses a set of metadata files to power its versioning feature.
+These files are located in the following locations:
+* `${VCPKG_ROOT}/port_versions/baseline.json`, (this file is common to all ports) and
+* `${VCPKG_ROOT}/port_versions/${first-letter-of-portname}-/${portname}.json` (one per port).
+
+For example, for `zlib` the relevant files are:
+* `${VCPKG_ROOT}/port_versions/baseline.json`
+* `${VCPKG_ROOT}/port_versions/z-/zlib.json`
+
+We expect that each time you update a port, you also update its version files.
+
+**The recommended method to update these files is to run the `x-add-version` command, e.g.:**
+
+```
+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 our [versioning specification](https://github.com/vicroms/vcpkg/blob/versioning-spec/docs/specifications/versioning.md) and [registries specification](https://github.com/strega-nil/vcpkg/blob/git-registries/docs/specifications/registries-2.md) to learn how vcpkg interacts with these files.
+
 ## Patching
 
 ### Prefer options over patching

scripts/azure-pipelines/windows/azure-pipelines.yml

@@ -51,6 +51,14 @@ jobs:
       filePath: 'scripts/azure-pipelines/end-to-end-tests.ps1'
       arguments: '-Triplet ${{ parameters.triplet }} -WorkingRoot ${{ variables.WORKING_ROOT }}'
       pwsh: true
+  - task: PowerShell@2
+    displayName: 'Validate version files'
+    condition: eq('${{ parameters.triplet }}', 'x86-windows')
+    inputs:
+      targetType: inline
+      script: |
+        ./vcpkg.exe --feature-flags=versions x-ci-verify-versions --verbose
+      pwsh: true
   - task: PowerShell@2
     displayName: '*** Test Modified Ports and Prepare Test Logs ***'
     inputs: