Prepare manual vcpkg release updates for minimal SQLite and Android curl

.github/scripts/prepare-vcpkg-release.py

@@ -0,0 +1,67 @@
+"""Copy the release's complete overlay port into a vcpkg checkout."""
+
+import argparse
+import json
+from pathlib import Path
+import re
+import shutil
+
+
+def prepare_port(source_port, destination_port, version, sha512):
+    if not re.fullmatch(r"\d+\.\d+\.\d+\.\d+", version):
+        raise ValueError("Expected a four-component SDK release version")
+    if not re.fullmatch(r"[0-9a-fA-F]{128}", sha512):
+        raise ValueError("Expected a 128-digit archive SHA512")
+    if destination_port.name != "cpp-client-telemetry" or destination_port.parent.name != "ports":
+        raise ValueError("Destination must be a ports/cpp-client-telemetry directory")
+    source_path = source_port.resolve()
+    destination_path = destination_port.resolve()
+    if (
+        source_path == destination_path
+        or source_path in destination_path.parents
+        or destination_path in source_path.parents
+    ):
+        raise ValueError("Source and destination ports must not overlap")
+
+    manifest = json.loads((source_port / "vcpkg.json").read_text(encoding="utf-8"))
+    if manifest["name"] != "cpp-client-telemetry":
+        raise ValueError("Release overlay is not the cpp-client-telemetry port")
+    for feature in ("minimal-sqlite", "android-curl-openssl"):
+        if feature not in manifest.get("features", {}):
+            raise ValueError(f"Release overlay is missing the {feature} feature")
+    manifest["version"] = version
+    manifest.pop("port-version", None)
+
+    portfile = (source_port / "portfile.cmake").read_text(encoding="utf-8")
+    for field, value in (("REF", f"v{version}"), ("SHA512", sha512)):
+        portfile, count = re.subn(
+            rf"(?m)^([ \t]*{field}[ \t]+)[^\r\n]+",
+            lambda match: match[1] + value,
+            portfile,
+        )
+        if count != 1:
+            raise ValueError(f"Release portfile must contain exactly one {field}")
+
+    # Replace the complete port so obsolete patches cannot survive a release.
+    if destination_port.exists():
+        shutil.rmtree(destination_port)
+    shutil.copytree(source_port, destination_port)
+    (destination_port / "portfile.cmake").write_text(portfile, encoding="utf-8", newline="\n")
+    (destination_port / "vcpkg.json").write_text(
+        json.dumps(manifest, indent=2) + "\n", encoding="utf-8", newline="\n"
+    )
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--source-port", type=Path, required=True)
+    parser.add_argument("--destination-port", type=Path, required=True)
+    parser.add_argument("--version", required=True)
+    parser.add_argument("--sha512", required=True)
+    arguments = parser.parse_args()
+    prepare_port(
+        arguments.source_port,
+        arguments.destination_port,
+        arguments.version,
+        arguments.sha512,
+    )

.github/workflows/test-vcpkg.yml

@@ -22,6 +22,18 @@ concurrency:
   cancel-in-progress: ${{ github.event_name == 'pull_request' }}
 
 jobs:
+  release-packaging:
+    runs-on: ${{ matrix.os }}
+    name: Release packaging (${{ matrix.os }})
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+    steps:
+    - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+    - name: Test release port promotion
+      run: python tests/vcpkg/test-release-port.py
+
   windows:
     runs-on: windows-latest
     name: Windows (x64-windows-static, ${{ matrix.transport }})
@@ -49,7 +61,11 @@ jobs:
 
   linux:
     runs-on: ubuntu-latest
-    name: Linux (x64-linux)
+    name: Linux (x64-linux, ${{ matrix.features }})
+    strategy:
+      fail-fast: false
+      matrix:
+        features: [default, minimal-sqlite]
     steps:
     - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
 
@@ -63,7 +79,7 @@ jobs:
         VCPKG_ROOT: ${{ runner.temp }}/vcpkg
       run: |
         chmod +x tests/vcpkg/test-vcpkg-linux.sh
-        ./tests/vcpkg/test-vcpkg-linux.sh
+        ./tests/vcpkg/test-vcpkg-linux.sh "${{ matrix.features }}"
 
   macos:
     runs-on: macos-latest
@@ -103,7 +119,11 @@ jobs:
 
   android:
     runs-on: ubuntu-latest
-    name: Android (arm64-v8a API 23 cross-compile)
+    name: Android (arm64-v8a API 23, ${{ matrix.features }})
+    strategy:
+      fail-fast: false
+      matrix:
+        features: [default, minimal-sqlite, "minimal-sqlite;android-curl-openssl", "minimal-sqlite;android-curl-mbedtls"]
     steps:
     - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
 
@@ -120,4 +140,4 @@ jobs:
         VCPKG_ROOT: ${{ runner.temp }}/vcpkg
       run: |
         chmod +x tests/vcpkg/test-vcpkg-android.sh
-        ./tests/vcpkg/test-vcpkg-android.sh arm64-v8a 23
+        ./tests/vcpkg/test-vcpkg-android.sh arm64-v8a 23 "${{ matrix.features }}"

docs/building-with-vcpkg.md

@@ -449,6 +449,40 @@ unchanged against the minimal build.
 
 ## How It Works
 
+### Promoting features on release
+
+After cutting an SDK release, maintainers manually prepare and submit the
+registry port update. There is no release-triggered workflow that creates a
+vcpkg PR, and no repository token is needed for port preparation.
+
+The [preparation helper](../.github/scripts/prepare-vcpkg-release.py) copies the
+**complete overlay port from the release tag**, not from the current development
+branch. It then replaces the archive
+`REF`, `SHA512`, and manifest version and removes any old `port-version`. This
+carries feature declarations and their CMake wiring together, including
+`minimal-sqlite` and the explicit Android curl backends. Run it from the released
+SDK checkout against a separate vcpkg checkout outside the SDK source tree.
+Start with a clean vcpkg working tree: the helper replaces the destination port,
+including existing patches.
+The helper requires Python 3.10 or newer and uses only the standard library.
+Pass the four-component version **without** its `v` prefix and the SHA512 of the
+published GitHub source `.tar.gz` archive, not an xcframework, AAR, or ZIP:
+
+```console
+python .github/scripts/prepare-vcpkg-release.py --source-port tools/ports/cpp-client-telemetry --destination-port <vcpkg>/ports/cpp-client-telemetry --version X.Y.Z.W --sha512 <release-archive-sha512>
+```
+
+Run `vcpkg format-manifest` on the resulting manifest and validate the downloaded
+release with `MATSDK_VCPKG_SOURCE_DIR` unset and without the SDK overlay before
+submitting the registry PR. Cover the default graph and the advertised opt-in
+features. Do not use the `tests/vcpkg` scripts for this release validation: they
+intentionally build the local SDK checkout instead of the pinned archive.
+The helper does not build, commit, push, or open a PR. After validating the port,
+commit its changes, update the vcpkg version database, and submit the registry PR
+using your normal local GitHub authentication.
+
+### Dependency and transport selection
+
 The SDK consumes canonical CMake dependency targets. The vcpkg toolchain
 provides those targets through normal `find_package()` discovery; no separate
 SDK-specific dependency-mode switch is required. Android transport selection is