[vcpkg manifest] Add documentation! (#13488)

* [vcpkg docs] add docs for manifest files

These are just for the maintainer docs,
not user docs.

* [vcpkg] EBNF-ify platform expression parsing

this modifies nothing about what strings are accepted or rejected,
it just moves stuff around.

also adds tests.

* [vcpkg docs] add manifest mode example

* [wip] docs for augustin

also fix tabs

* [vcpkg manifest] switch to using maps for features

* Apply suggestions from code review

* un-experimentize format-manifest

* flesh out the user manifest mode docs

* CRs

* billy CRs

* final personal pass-thru

4 files changed, 477 insertions, 40 deletions

diff --git a/docs/maintainers/control-files.md b/docs/maintainers/control-files.md
index e20669b33..ab5f0eea3 100644
--- a/docs/maintainers/control-files.md
+++ b/docs/maintainers/control-files.md
@@ -1,5 +1,8 @@
 # CONTROL files
 
+CONTROL files are retained for backwards compatibility with earlier versions of vcpkg;
+all new features are added only to vcpkg.json, and we recommend using vcpkg.json for any newly authored port.
+
 The `CONTROL` file contains metadata about the port.  The syntax is based on [the Debian `control` format][debian] although we only support the subset of fields documented here.
 
 Field names are case-sensitive and start the line without leading whitespace.  Paragraphs are separated by one or more empty lines.
diff --git a/docs/maintainers/maintainer-guide.md b/docs/maintainers/maintainer-guide.md
index e0fde7e68..372771b08 100644
--- a/docs/maintainers/maintainer-guide.md
+++ b/docs/maintainers/maintainer-guide.md
@@ -128,25 +128,32 @@ A lib is considered conflicting if it does any of the following:
 

 Conflicting libs are typically by design and not considered a defect.  Because some build systems link against everything in the lib directory, these should be moved into a subdirectory named `manual-link`.

 

+## Manifests and CONTROL files

+

+When adding a new port, use the new manifest syntax for defining a port;

+you may also change over to manifests when modifying an existing port.

+You may do so easily by running the `vcpkg format-manifest` command, which will convert existing CONTROL

+files into manifest files. Do not convert CONTROL files that have not been modified.

+

 ## Versioning

 

-### Follow common conventions for the `Version:` field

+### Follow common conventions for the `"version"` field

 

-See our [CONTROL files document](control-files.md#version) for a full explanation of our conventions.

+See our [manifest files document](manifest-files.md#version-fields) for a full explanation of our conventions.

 

-### Update the `Version:` field in the `CONTROL` file of any modified ports

+### Update the `"port-version"` field in the manifest file of any modified ports

 

 Vcpkg uses this field to determine whether a given port is out-of-date and should be changed whenever the port's behavior changes.

 

-Our convention for this field is to append a `-N` to the upstream version when changes need to be made.

+Our convention is to use the `"port-version"` field for changes to the port that don't change the upstream version, and to reset the `"port-version"` back to zero when an update to the upstream version is made.

 

 For Example:

 

-- Zlib's package version is currently `1.2.1`.

+- Zlib's package version is currently `1.2.1`, with no explicit `"port-version"` (equivalent to a `"port-version"` of `0`).

 - You've discovered that the wrong copyright file has been deployed, and fixed that in the portfile.

-- You should update the `Version:` field in the control file to `1.2.1-1`.

+- You should update the `"port-version"` field in the manifest file to `1`.

 

-See our [CONTROL files document](control-files.md#version) for a full explanation of our conventions.

+See our [manifest files document](manifest-files.md#port-version) for a full explanation of our conventions.

 

 ## Patching

 

@@ -212,7 +219,7 @@ Finally, DLL files on Windows should never be renamed post-build because it brea
 

 ### Vcpkg internal code

 

-We require the c/c++ code inside vcpkg to follow the clang-format, if you change them. Please perform the following steps after modification:

+We require the C++ code inside vcpkg to follow the clang-format, if you change them. Please perform the following steps after modification:

 

 - Use Visual Studio:

 1. Configure your [clang-format tools](https://devblogs.microsoft.com/cppblog/clangformat-support-in-visual-studio-2017-15-7-preview-1/).

@@ -226,15 +233,13 @@ We require the c/c++ code inside vcpkg to follow the clang-format, if you change
 > LLVM_PATH/bin/clang-format.exe -style=file -i changed_file.cpp

 ```

 

-### Manifest

+### Manifests

 

-We require that the manifest file needs to be formatted, perform the following steps to solve this issue:

+We require that the manifest file be formatted. Use the following command to format all manifest files:

 

-1. Format all changed manifest files.

 ```cmd

-> vcpkg x-format-manifest --all

+> vcpkg format-manifest --all

 ```

-2. Commit changes to your branch.

 

 ## Useful implementation notes

 

diff --git a/docs/maintainers/manifest-files.md b/docs/maintainers/manifest-files.md
new file mode 100644
index 000000000..001ca871d
--- /dev/null
+++ b/docs/maintainers/manifest-files.md
@@ -0,0 +1,420 @@
+# Manifest files - `vcpkg.json`
+
+The `vcpkg.json` file contains metadata about the port.
+It's a JSON file, and replaces the existing CONTROL file metadata structure.
+It must have a top level object, and all fields are case sensitive.
+
+## Examples:
+
+The most important fields in a manifest, the ones which are required for all ports,
+are the `"name"` field, and a version field (for now, just `"version-string"`).
+There's more information about these fields below.
+
+```json
+{
+  "name": "ace",
+  "version-string": "6.5.5"
+}
+```
+
+```json
+{
+  "name": "vtk",
+  "version-string": "8.2.0",
+  "port-version": 2,
+  "description": "Software system for 3D computer graphics, image processing, and visualization",
+  "dependencies": [
+    {
+      "name": "atlmfc",
+      "platform": "windows"
+    },
+    "double-conversion",
+    "eigen3",
+    "expat",
+    "freetype",
+    "glew",
+    "hdf5",
+    "jsoncpp",
+    "libharu",
+    "libjpeg-turbo",
+    "libpng",
+    "libtheora",
+    "libxml2",
+    "lz4",
+    "netcdf-c",
+    "proj4",
+    "pugixml",
+    "sqlite3",
+    "tiff",
+    "zlib"
+  ]
+}
+```
+
+## Fields
+
+### `"name"`
+The name of the port.
+
+When adding new ports be aware that the name may conflict with other projects that are not a part of vcpkg.  For example `json` conflicts with too many other projects so you should add a scope to the name such as `taocpp-json` to make it unique.  Verify there are no conflicts on a search engine as well as on other package collections.
+
+Package collections to check for conflicts:
+
++ [Repology](https://repology.org/projects/)
++ [Debian packages](https://www.debian.org/distrib/packages)
++ [Packages search](https://pkgs.org/)
+
+A name must be an identifier: i.e., it must only consist of lowercase ascii alphabetic characters,
+numbers, and hyphens, and it must not begin nor end with a hyphen.
+
+### Version fields
+
+The library version. There is currently only one kind of version, a `"version-string"` -
+however, more version kinds will be added later. Additionally,
+`"port-version"` is used to differentiate between port changes that don't change the underlying library version.
+
+#### `"version-string"`
+
+This field is an ascii string, and may contain alphanumeric characters, `.`, `_`, or `-`. No attempt at ordering versions is made; all versions are treated as byte strings and are only evaluated for equality.
+
+For tagged-release ports, we follow the following convention:
+
+1. If the library follows a scheme like `va.b.c`, we remove the leading `v`. In this case, it becomes `a.b.c`.
+2. If the library includes its own name in the version like `curl-7_65_1`, we remove the leading name: `7_65_1`
+3. If the library is versioned by dates, format the resulting version string just like the upstream library;
+   for example, Abseil formats their dates `lts_2020_02_25`, so the `"version-string"` should be `"lts_2020_02_25"`.
+
+For rolling-release ports, we use the date that the _commit was accessed by you_, formatted as `YYYY-MM-DD`. Stated another way: if someone had a time machine and went to that date, they would see this commit as the latest master.
+
+For example, given:
+1. The latest commit was made on 2019-04-19
+2. The current version string is `2019-02-14`
+3. Today's date is 2019-06-01.
+
+Then if you update the source version today, you should give it version `2019-06-01`.
+
+#### `"port-version"`
+
+The version of the port, aside from the library version.
+
+This field is a non-negative integer.
+It allows one to version the port file separately from the version of the underlying library;
+if you make a change to a port, without changing the underlying version of the library,
+you should increment this field by one (starting at `0`, which is equivalent to no `"port-version"` field).
+When the version of the underlying library is upgraded,
+this field should be set back to `0` (i.e., delete the `"port-version"` field).
+
+#### Examples:
+```json
+{
+  "version": "1.0.5",
+  "port-version": 2
+}
+```
+
+```json
+{
+  "version": "2019-03-21"
+}
+```
+
+### `"description"`
+
+A description of the library.
+
+This field can either be a single string, which should be a summary of the library,
+or can be an array, with the first line being a summary and the remaining lines being the detailed description -
+one string per line.
+
+#### Examples:
+```json
+{
+  "description": "C++ header-only JSON library"
+}
+```
+```json
+{
+  "description": [
+    "Mosquitto is an open source message broker that implements the MQ Telemetry Transport protocol versions 3.1 and 3.1.1.",
+    "MQTT provides a lightweight method of carrying out messaging using a publish/subscribe model."
+    "This makes it suitable for 'machine to machine' messaging such as with low power sensors or mobile devices such as phones, embedded computers or microcontrollers like the Arduino."
+  ]
+}
+```
+
+### `"homepage"`
+
+The URL of the homepage for the library where a user is able to find additional documentation or the original source code.
+
+### `"documentation"`
+
+The URL where a user would be able to find official documentation for the library. Optional.
+
+### `"maintainers"`
+
+A list of strings that define the set of maintainers of a package.
+It's recommended that these take the form of `Givenname Surname <email>`,
+but this field is not checked for consistency.
+
+Optional.
+
+#### Example:
+```json
+{
+  "homepage": "https://github.com/microsoft/vcpkg"
+}
+```
+
+### `"dependencies"`
+
+An array of ports the library has a dependency on.
+
+vcpkg does not distinguish between build-only dependencies and runtime dependencies.
+The complete list of dependencies needed to successfully use the library should be specified.
+
+For example: websocketpp is a header only library, and thus does not require any dependencies at install time.
+However, downstream users need boost and openssl to make use of the library.
+Therefore, websocketpp lists boost and openssl as dependencies.
+
+Each dependency may be either an identifier, or an object.
+For many dependencies, just listing the name of the library should be fine;
+however, if one needs to add extra information to that dependency, one may use the dependency object.
+For a dependency object, the `"name"` field is used to designate the library;
+for example the dependency object `{ "name": "zlib" }` is equivalent to just writing `"zlib"`.
+
+If the port is dependent on optional features of another library,
+those can be specified using the `"features"` field of the dependency object.
+If the port does not require any features from the dependency,
+this should be specifed with the `"default-features"` fields set to `false`.
+
+Dependencies can also be filtered based on the target triplet to support differing requirements.
+These filters use the same syntax as the `"supports"` field below,
+and are specified in the `"platform"` field.
+
+#### Example:
+```json
+{
+  "dependencies": [
+    {
+      "name": "curl",
+      "default-features": false,
+      "features": [
+        "winssl"
+      ],
+      "platform": "windows"
+    },
+    {
+      "name": "curl",
+      "default-features": false,
+      "features": [
+        "openssl"
+      ],
+      "platform": "!windows"
+    },
+    "rapidjson"
+  ]
+}
+```
+
+### `"features"`
+
+Multiple optional features can be specified in manifest files, in the `"features"` object field.
+This field is a map from the feature name, to the feature's information.
+Each one must have a `"description"` field, and may also optionally have a `"dependencies"` field.
+
+A feature's name must be an identifier -
+in other words, lowercase alphabetic characters, digits, and hyphens,
+neither starting nor ending with a hyphen.
+
+A feature's `"description"` is a description of the feature,
+and is the same kind of thing as the port `"description"` field.
+
+A feature's `"dependencies"` field contains the list of extra dependencies required to build and use this feature;
+this field isn't required if the feature doesn't require any extra dependencies.
+On installation the dependencies from all selected features are combined to produce the full dependency list for the build.
+
+#### Example:
+
+```json
+{
+  "name": "vtk",
+  "version-string": "8.2.0",
+  "port-version": 2,
+  "description": "Software system for 3D computer graphics, image processing, and visualization",
+  "dependencies": [
+    {
+      "name": "atlmfc",
+      "platform": "windows"
+    },
+    "double-conversion",
+    "eigen3",
+    "expat",
+    "freetype",
+    "glew",
+    "hdf5",
+    "jsoncpp",
+    "libharu",
+    "libjpeg-turbo",
+    "libpng",
+    "libtheora",
+    "libxml2",
+    "lz4",
+    "netcdf-c",
+    "proj4",
+    "pugixml",
+    "sqlite3",
+    "tiff",
+    "zlib"
+  ],
+  "features": {
+    "mpi": {
+      "description": "MPI functionality for VTK",
+      "dependencies": [
+        {
+          "name": "hdf5",
+          "features": [
+            "parallel"
+          ]
+        },
+        "mpi"
+      ]
+    },
+    "openvr": {
+      "description": "OpenVR functionality for VTK",
+      "dependencies": [
+        "openvr",
+        "sdl2"
+      ]
+    },
+    "python": {
+      "description": "Python functionality for VTK",
+      "dependencies": [
+        "python3"
+      ]
+    },
+    "qt": {
+      "description": "Qt functionality for VTK",
+      "dependencies": [
+        "qt5"
+      ]
+    }
+  }
+}
+```
+
+### `"default-features"`
+
+An array of feature names that the library uses by default, if nothing else is specified.
+
+#### Example:
+```json
+{
+  "default-features": [
+    "kinesis"
+  ],
+  "features": {
+    "dynamodb": {
+      "description": "Build dynamodb support",
+      "dependencies": [
+        "dynamodb"
+      ]
+    },
+    "kinesis": {
+      "description": "build kinesis support"
+    }
+  }
+}
+```
+
+### `"supports"`
+
+A string, formatted as a platform expression,
+that evaluates to true when the port should build successfully for a triplet.
+
+This field is used in the CI testing to skip ports,
+and warns users in advance that a given install tree is not expected to succeed.
+Therefore, this field should be used optimistically;
+in cases where a port is expected to succeed 10% of the time, it should still be marked "supported".
+
+The grammar for this top-level platform expression, in [EBNF], is as follows:
+
+```ebnf
+whitespace-character =
+| ? U+0009 "CHARACTER TABULATION" ?
+| ? U+000A "LINE FEED" ?
+| ? U+000D "CARRIAGE RETURN" ?
+| ? U+0020 "SPACE" ? ;
+optional-whitespace = { whitespace-character } ;
+
+lowercase-alpha =
+| "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" | "i" | "j" | "k" | "l" | "m"
+| "n" | "o" | "p" | "q" | "r" | "s" | "t" | "u" | "v" | "w" | "x" | "y" | "z" ;
+digit =
+| "0" | "1" | "2" | "3" | "4"
+| "5" | "6" | "7" | "8" | "9" ;
+identifier-character =
+| lowercase-alpha
+| digit ;
+
+platform-expression =
+| platform-expression-not
+| platform-expression-and
+| platform-expression-or ;
+
+platform-expression-identifier = 
+| identifier-character, { identifier-character }, optional-whitespace ;
+
+platform-expression-simple =
+| platform-expression-identifier
+| "(", optional-whitespace, platform-expression, ")", optional-whitespace ;
+
+platform-expression-not =
+| platform-expression-simple
+| "!", optional-whitespace, platform-expression-simple ;
+
+platform-expression-and =
+| platform-expression-not, { "&", optional-whitespace, platform-expression-not } ;
+
+platform-expression-or =
+| platform-expression-not, { "|", optional-whitespace, platform-expression-not } ;
+
+top-level-platform-expression = optional-whitespace, platform-expression ;
+```
+
+Basically, there are four kinds of expressions -- identifiers, negations, ands, and ors.
+Negations may only negate an identifier or a grouped expression.
+Ands and ors are a list of `&` or `|` separated identifiers, negated expressions, and grouped expressions.
+One may not mix `&` and `|` without parentheses for grouping.
+
+These predefined identifier expressions are computed from standard triplet settings:
+- `x64` - `VCPKG_TARGET_ARCHITECTURE` == `"x64"`
+- `x86` - `VCPKG_TARGET_ARCHITECTURE` == `"x86"`
+- `arm` - `VCPKG_TARGET_ARCHITECTURE` == `"arm"` or `VCPKG_TARGET_ARCHITECTURE` == `"arm64"`
+- `arm64` - `VCPKG_TARGET_ARCHITECTURE` == `"arm64"`
+- `windows` - `VCPKG_CMAKE_SYSTEM_NAME` == `""` or `VCPKG_CMAKE_SYSTEM_NAME` == `"WindowsStore"`
+- `uwp` - `VCPKG_CMAKE_SYSTEM_NAME` == `"WindowsStore"`
+- `linux` - `VCPKG_CMAKE_SYSTEM_NAME` == `"Linux"`
+- `osx` - `VCPKG_CMAKE_SYSTEM_NAME` == `"Darwin"`
+- `android` - `VCPKG_CMAKE_SYSTEM_NAME` == `"Android"`
+- `static` - `VCPKG_LIBRARY_LINKAGE` == `"static"`
+- `wasm32` - `VCPKG_TARGET_ARCHITECTURE` == `"wasm32"`
+- `emscripten` - `VCPKG_CMAKE_SYSTEM_NAME` == `"Emscripten"`
+
+These predefined identifier expressions can be overridden in the triplet file,
+via the [`VCPKG_DEP_INFO_OVERRIDE_VARS`](../users/triplets.md) option,
+and new identifier expressions can be added via the same mechanism.
+
+This field is optional and defaults to true.
+
+> Implementers' Note: these terms are computed from the triplet via the `vcpkg_get_dep_info` mechanism.
+
+[EBNF]: https://en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_form
+
+#### Example:
+```json
+{
+  "supports": "!uwp & !(arm & !arm64)"
+}
+```
+
+This means "doesn't support uwp, nor arm32 (but does support arm64)".
diff --git a/docs/maintainers/pr-review-checklist.md b/docs/maintainers/pr-review-checklist.md
index 44aa46741..ce8d1c3a9 100644
--- a/docs/maintainers/pr-review-checklist.md
+++ b/docs/maintainers/pr-review-checklist.md
@@ -1,6 +1,6 @@
 Vcpkg PR Checklist
 =====================
-Revision: 0
+Revision: 1
 
 ## Overview
 This document provides an annotated checklist which vcpkg team members use to apply the "reviewed" label on incoming pull requests. If a pull request violates any of these points, we may ask contributors to make necessary changes before we can merge the changeset.
@@ -10,87 +10,87 @@ Feel free to create an issue or pull request if you feel that this checklist can
 ## Checklist
 You can link any of these checklist items in a GitHub comment by copying the link address attached to each item code.
 
-<details id=c000001>
-<summary><a href=#c000001>c000001</a>: No deprecated helper functions are used</summary>
+<details id="c000001">
+<summary><a href="#c000001">c000001</a>: No deprecated helper functions are used</summary>
 
 See our [Maintainer Guidelines and Policies](maintainer-guide.md#Avoid-deprecated-helper-functions) for more information.
 
 </details>
 
-<details id=c000002>
-<summary><a href=#c000002>c000002</a>: Control Version field is updated</summary>
+<details id="c000002">
+<summary><a href="#c000002">c000002</a>: `"port-version"` field is updated</summary>
 
 See our [Maintainer Guidelines and Policies](maintainer-guide.md#versioning) for more information.
 
 </details>
 
-<details id=c000003>
-<summary><a href=#c000003>c000003</a>: New ports contain a Description field written in English</summary>
+<details id="c000003">
+<summary><a href="#c000003">c000003</a>: New ports contain a `"description"` field written in English</summary>
 
 A description only one or a few sentences long is helpful. Consider using the library's official description from their `README.md` or similar if possible. Automatic translations are acceptable and we are happy to clean up translations to English for our contributors.
 
-See our [CONTROL file documentation](https://github.com/grdowns/vcpkg/blob/pr-checklist/docs/maintainers/control-files.md#description) for more information.
+See our [manifest file documentation](manifest-files.md#description) for more information.
     
 </details>
 
-<details id=c000004>
-    <summary><a href=#c000004>c000004</a>: No unnecessary comments are present in the changeset</summary>
+<details id="c000004">
+<summary><a href="#c000004">c000004</a>: No unnecessary comments are present in the changeset</summary>
 
 See our [Maintainer Guidelines and Policies](maintainer-guide.md#Avoid-excessive-comments-in-portfiles) for more information.
 
 </details>
 
-<details id=c000005>
-<summary><a href=#c000005>c000005</a>: Downloaded archives are versioned if available</summary
+<details id="c000005">
+<summary><a href="#c000005">c000005</a>: Downloaded archives are versioned if available</summary
 
-To ensure archive content does not change, archives downloaded preferably have an associated version tag that can be incremented alongside the port version.
+To ensure archive content does not change, archives downloaded preferably have an associated version tag that can be incremented alongside the port's `"version"`.
 
 </details>
 
-<details id=c000006>
-<summary><a href=#c000006>c000006</a>: New ports pass CI checks for triplets that the library officially supports</summary>
+<details id="c000006">
+<summary><a href="#c000006">c000006</a>: New ports pass CI checks for triplets that the library officially supports</summary>
 
 To ensure vcpkg ports are of a high quality, we ask that incoming ports support the official platforms for the library in question.
 
 </details>
 
-<details id=c000007>
-<summary><a href=#c000007>c000007</a>: Patches fix issues that are vcpkg-specific only</summary>
+<details id="c000007">
+<summary><a href="#c000007">c000007</a>: Patches fix issues that are vcpkg-specific only</summary>
 
 If possible, patches to the library source code should be upstreamed to the library's official repository. Opening up a pull request on the library's repository will help to improve the library for everyone, not just vcpkg users.
 
 </details>
 
-<details id=c000008>
-<summary><a href=#c000008>c000008</a>: New ports download source code from the official source if available</summary>
+<details id="c000008">
+<summary><a href="#c000008">c000008</a>: New ports download source code from the official source if available</summary>
 
 To respect library authors and keep code secure, please have ports download source code from the official source. We may make exceptions if the original source code is not available and there is substantial community interest in maintaining the library in question.
 
 </details>
 
-<details id=c000009>
-<summary><a href=#c000010>c000010</a>: Ports and port features are named correctly</summary>
+<details id="c000009">
+<summary><a href="#c000009">c000009</a>: Ports and port features are named correctly</summary>
 
 For user accessibility, we prefer names of ports and port features to be intuitive and close to their counterparts in official sources and other package managers. If you are unsure about the naming of a port or port feature, we recommend checking repology.org, packages.ubuntu.com, or searching for additional information using a search engine. We can also help our contributors with this, so feel free to ask for naming suggestions if you are unsure.
 
 </details>
 
-<details id=c000010>
-<summary><a href=#c000011>c000011</a>: Library targets are exported when appropriate</summary>
+<details id="c000010">
+<summary><a href="#c000010">c000010</a>: Library targets are exported when appropriate</summary>
 
 To provide users with a seamless build system integration, please be sure to export and provide a means of finding the library targets intended to be used downstream. Targets not meant to be exported should be be marked private and not exported.
 
 </details>
 
-<details id=c000011>
-<summary><a href=#c000012>c000012</a>: Ports do not use applications which modify the user's system</summary>
+<details id="c000011">
+<summary><a href="#c000011">c000011</a>: Ports do not use applications which modify the user's system</summary>
     
 Ports should uphold vcpkg's contract of not modifying the user's system by avoiding applications which do so. Examples of these applications are `sudo`, `apt`, `brew`, or `pip`. Please use an alternative to these types of programs wherever possible.
 
 </details>
 
-<details id=c000012>
-<summary><a href=#c000013>c000013</a>: Ports with system dependencies include an information message during installation</summary>
+<details id="c000012">
+<summary><a href="#c000012">c000012</a>: Ports with system dependencies include an information message during installation</summary>
 
 Some ports have library and tool dependencies that do not exist within vcpkg. For these missing dependencies, we ask that contributors add a message to the top of the port's `portfile.cmake` stating the missing dependencies and how to acquire them. We ask that the message is displayed before any major work is done to ensure that users can "early out" of the installation process as soon as possible in case they are missing the dependency.
 
@@ -104,3 +104,12 @@ These can be installed on Ubuntu systems via sudo apt install autoconf libtool"
 ```
 
 </details>
+
+<details id="c000013">
+<summary><a href="#c000013">c000013</a>: Manifest files are used instead of CONTROL files for new ports</summary>
+
+Many existing ports use the CONTROL file syntax; while this syntax will be supported for some time to come,
+new ports should not use these. Any newly added port _must_ use the manifest files.
+
+We also recommend, when significant modifications are made to ports, that one switches to manifest files;
+however, this is not required. You may find `vcpkg format-manifest` useful.