From f649f9a67e0769aabb04f02ccaba816abd0089e2 Mon Sep 17 00:00:00 2001
From: Victor Romero <romerosanchezv@gmail.com>
Date: Thu, 14 Jan 2021 21:29:15 -0800
Subject: [PATCH] [vcpkg] Add CI check for version files and update
 maintainer's guideline (#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          | 31 +++++++++++++++++++
 .../windows/azure-pipelines.yml               |  8 +++++
 2 files changed, 39 insertions(+)

diff --git a/docs/maintainers/maintainer-guide.md b/docs/maintainers/maintainer-guide.md
index 734bcc5d9fe..6ceb519125b 100644
--- a/docs/maintainers/maintainer-guide.md
+++ b/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
diff --git a/scripts/azure-pipelines/windows/azure-pipelines.yml b/scripts/azure-pipelines/windows/azure-pipelines.yml
index c78c3d9ee8d..a7fb6408bda 100644
--- a/scripts/azure-pipelines/windows/azure-pipelines.yml
+++ b/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: