port-upgrade

name	port-upgrade
description	Use when: upgrading cmake-toolset ports, checking upstream releases, resolving dependency pins, validating patches, handling cross-compiling host tools, or reviewing CI impact.
argument-hint	ports=<names|all>; mode=analyze|update; validate=patch|build|ci|full; notes=<optional>

Port Upgrade Workflow

Use this skill to upgrade one or more ports while preserving dependency compatibility, patch behavior, and repository-specific guards.

Input Form

Parse the user's request with this form:

• ports= required; one or more port names, or all.
• mode= analyze or update; default is update.
• validate= patch, build, ci, or full; default is patch.
  • patch: patch validation only.
  • build: version, patch, and local build validation.
  • ci: CI impact review.
  • full: local build validation plus CI impact review.
• notes= optional extra constraints.

If a field is missing, infer safe defaults and ask only for blocking missing information.

Workflow

Phase 0: Preflight Classification

• Classify the entry file as a standard port, aggregator, orchestrator, complex port, or cross-compiling host port.
• Read the truth sources:
  • upstream repo at the target tag
  • ports/Configure.cmake
  • test/CMakeLists.txt
  • .github/workflows/build.yaml and ci/do_ci.*
• For port files, patches, test integration, CI entrypoints, and workflow matrices, also follow repository-maintenance-guidelines.md.
• Record compiler/version fallbacks, hosted tools, RTTI/visibility logic, cross-compiling support, and backend exclusions.

Phase 1: Version Survey

• Find all current version declarations and related tag or compiler fallback logic.
• Fetch the latest stable upstream releases.
• Build a table of current vs target versions.

Phase 2: Dependency Analysis

• Query upstream build metadata such as MODULE.bazel, WORKSPACE, bazel/*_deps.bzl, CMakeLists.txt, and cmake/*.cmake.
• Use test/CMakeLists.txt for repository include order and local compatibility guards.
• When multiple ports pin the same dependency differently, use the highest commonly supported version or report the conflict.
• See dependency-chains.md.

Phase 3: Special-Case Analysis

• Any import.cmake under ports/ is an aggregator. Known aggregators: compression/, algorithm/, grpc/, ngtcp2/, telemetry/, test/, web/.
• Treat aggregators and orchestrators as grouped logic, not template-only edits.
• Preserve compiler fallbacks, backend exclusions, RTTI/visibility logic, and hosted-tool behavior unless validated.
• For crosscompiling-host/, hosted tools, or .cross.patch, follow cross-compilation.md.
• Treat ssl/port.cmake, grpc/import.cmake, and protobuf/protobuf.cmake as custom logic.

Phase 4: Version Updates

• Update all relevant version, tag, and conditional references.
• Check tag-format changes and multiple version sites.

Phase 5: Patch Validation

• Reuse same-minor patch files when they still apply cleanly.
• Create a new patch only when the content differs.
• Validate .cross.patch separately when relevant.
• Use --depth 1 for patch testing and clean up test/third_party/packages/ afterward.
• See patch-workflow.md.

Phase 6: Deprecated Build Options

• Check upstream changelogs and CMake files for option removals or renames.
• See deprecated-options.md.

Phase 7: Integration and CI Verification

• Confirm versions, tags, build options, and patch names.
• Review test/CMakeLists.txt, .github/workflows/build.yaml, and ci/do_ci.* for impacted combinations.
• Summarize changes, validation, and remaining risks.

Important Rules

• Protect incremental builds. Treat unconditional touch or same-content overwrites of code/resources consumed by add_custom_command, add_custom_target, add_executable, add_library, or target_sources as a blocking defect, including generated and copied files. Require real OUTPUT/BYPRODUCTS, accurate DEPENDS/DEPFILE, and content-stable publication (or a temporary file plus cmake -E copy_if_different). A stamp/witness must not be a compiled, linked, packaged, or installed input.
• Pre-commit formatting is mandatory. Before committing, run cmake-format -i on every modified .cmake, .cmake.in, and CMakeLists.txt file (excluding test/third_party/ and test/build_jobs_*/). Alternatively run bash ci/format.sh to format the entire tree. CI will reject unformatted files.
• Repository maintenance rules are shared. When touching port CMake files, patches, test/CMakeLists.txt, ci/do_ci.*, or .github/workflows/*.yaml, follow repository-maintenance-guidelines.md.
• Never update a dependency without checking its dependents. Always query upstream repos for actual version pins rather than assuming from memory.
• Repository include order comes from test/CMakeLists.txt.
• Patch files are matched by minor version prefix. A patch for v1.9.4 will match v1.9.5 automatically. Only create a new patch if the content actually differs.
• Ports with crosscompiling-host/ assets or hosted tools require host-side validation.
• Preserve repository-specific guards. Existing no-exception, no-rtti, compiler-version, and backend exclusions are compatibility knowledge, not dead code.
• Cross-compilation patches (.cross.patch) are separate from regular patches and must be tested independently.

Known Issues

• c-ares: Some versions have Windows build failures. Check CI notes before updating.