vcpkg 仓库贡献指南：Port Patch 文件管理与 Pull Request 提交流程规范

vcpkg 仓库贡献指南：Port Patch 文件管理与 Pull Request 提交流程规范

【免费下载链接】vcpkgC++ Library Manager for Windows, Linux, and MacOS项目地址: https://gitcode.com/GitHub_Trending/vc/vcpkg

导读

本文基于 vcpkg 仓库根目录的 AGENTS.md（并被 CLAUDE.md 以@AGENTS.md方式引用的 AI 协作规范），系统讲解向 vcpkg 提交贡献时必须遵循的两类硬性约定：Port Patch 文件的创建/刷新方式（git diff --output与 CRLF 行结尾问题）与Pull Request 的 Checklist 与审查预期。读者将掌握如何生成行结尾无损的 patch 文件、如何正确填写端口更新/新端口两种 PR 清单、以及维护者在审查时会重点核查哪些包就绪证据，从而显著减少提交被驳回的风险。

vcpkg 是一个面向 Windows、Linux、macOS 的 C++ 库管理器，仓库主体是数以千计的ports/<port-name>/目录（每个端口由portfile.cmake与vcpkg.json描述）以及配套的versions/版本数据库。AGENTS.md虽篇幅不长，却是 AI 辅助贡献者（如 Claude Code 等 Agent）在处理本仓库时的"操作手册"，其技术内容与仓库的构建系统、版本数据库和 PR 审查流水线深度耦合。

一、AGENTS.md 在仓库中的定位

AGENTS.md位于仓库根目录，与CLAUDE.md、CONTRIBUTING.md、CONTRIBUTING_zh.md共同构成贡献文档体系，但职责分工不同：

从结构看，AGENTS.md可以被理解为对CONTRIBUTING.md中"新包贡献准则"的机器可读补充：它把最容易出错的机械性操作（patch 行结尾、清单勾选、审查依据）固化为 Agent 必须遵守的规则。

二、Port Patch 文件：为什么必须用git diff --output

2.1 规则原文

Create or refresh patch files withgit diff --output=<patch-file> ..., not shell output redirection. This preserves exact line endings, including CRLF bytes in patch hunks.

即：创建或刷新 patch 文件时必须使用git diff --output=<patch-file> ...，禁止使用git diff ... > patch-file这类 shell 输出重定向。原因是前者能保留精确的行结尾，包括 patch hunk 中的 CRLF 字节。

2.2 底层原因：CRLF 与统一 diff 的冲突

• 仓库中大量上游项目（尤其是 Windows 生态的 C/C++ 库）源文件使用CRLF（\r\n）行结尾。生成 patch 时，diff 的 hunk 行必须逐字节匹配目标文件才能被git apply/patch成功套用。
• shell 输出重定向（>）默认按文本模式处理输出，可能会对行结尾做转换或剥离（取决于 shell/管道配置），导致 patch hunk 中的\r字节丢失。当 patch 用于修补 CRLF 文件时，hunk 行结尾与文件内容不匹配，git apply会报错或产生错误的行尾混合。
• git diff --output=<file>由 Git 自身以二进制保真方式写出 diff 结果，对 hunk 中的 CRLF 字节原样保留，从而保证 patch 在任何平台、任何流水线中都能稳定套用。

这一约束在维护者审查指南 .github/skills/shared/review-vcpkg-pr-guide.md 的第 18 条审查项中也有对应表述：patch 文件通常应为 LF 行结尾，但在修补 CRLF 内容的 hunk 行中允许 CRLF——这正是git diff --output的输出形态（忽略index扩展头差异）。

2.3 仓库中的实际形态

在ports/下几乎每个端口目录都包含 patch 文件与 portfile 的应用调用。以 ports/abseil/portfile.cmake 为例：

vcpkg_from_github( OUT_SOURCE_PATH SOURCE_PATH REPO abseil/abseil-cpp REF "${VERSION}" SHA512 f5012885d6b6844a9cf5ed92ad5468b8757db33dfe1364bfb232fff928e06c550c7eb4557f45186a8ac4d18b178df9be267681abab4a6de40823b574afbe9960 HEAD_REF master PATCHES 003-force-cxx-17.patch fix-heterogeneous_lookup_testing-target.patch fix-mingw-dll.patch fix-gcc13-constexpr-function-pointer.patch )

• PATCHES字段按顺序应用；端口更新版本时往往需要刷新这些 patch（重新基于新 tag 生成）。
• 刷新流程即：git diff --output=ports/abseil/003-force-cxx-17.patch <old-ref>..<new-ref> -- <path>一类的命令（结合git format-patch亦可）。
• 修改 port 或升级版本后，必须同步更新SHA512（新下载归档的校验值），并执行./vcpkg x-add-version --all刷新versions/数据库——这两点正是 PR 清单中的硬性条目。

从源码结构可以推断：vcpkg 的构建流水线（CI）会在目标三元组（triplet）上实际下载源码、套用PATCHES、执行构建与安装；任何一个 patch 因行结尾问题套用失败，都会直接导致端口构建失败。因此 patch 文件的字节级正确性不是风格问题，而是构建成败问题。

三、Pull Request：Checklist 的正确使用方式

3.1 规则原文

Before opening or drafting a pull request, read.github/pull_request_template.md, determine which checklist applies, and verify each relevant item. Keep / uncomment applicable checklists in pull request bodies and complete them accurately. Do not make up your own checklists.

含义：

1. 提交 PR（含 Draft）之前必须先阅读 .github/pull_request_template.md；
2. 判定本次改动属于哪种类型（更新现有端口 / 新增端口），确定适用的 Checklist；
3. 保留并取消注释模板中对应的 Checklist 区块，逐项如实完成；严禁自创清单。

3.2 模板中的两种 Checklist

.github/pull_request_template.md 内嵌了两段被注释的清单，提交时按场景取消注释：

端口更新清单（PORT UPDATE CHECKLIST）逐项包括：

• 变更符合维护者指南（maintainer guide）；
• 每个更新的下载源已同步更新SHA512；
• "supports"子句如实反映新版本可能修复的平台，或声明无需变更；
• 若修复了 scripts/ci.baseline.txt 或scripts/ci.feature.baseline.txt中记录的失败项，需从基线文件中移除对应条目；
• 端口内所有 patch 文件均被应用且成功；
• 通过重新运行./vcpkg x-add-version --all修复版本数据库并提交结果；
• 每个被修改的versions/*.json文件中恰好新增一个版本。

新端口清单（NEW PORT CHECKLIST）在更新清单基础上追加了更多包就绪核查：

• 被打包的项目足够成熟、适合向 vcpkg 用户广泛提供（如已有至少 6 个月的发布或公开开发历史）；
• 端口名称与上游项目强关联（Repology 索引、搜索引擎前列结果、或GitHubOrg-GitHubRepo命名形态）；
• 构建的所有可选依赖均受端口控制（要么在vcpkg.json中无条件声明，要么通过 patch 或构建参数如CMAKE_DISABLE_FIND_PACKAGE_Xxx、VCPKG_LOCK_FIND_PACKAGE显式禁用）；
• vcpkg.json中的版本方案、许可证声明与上游一致；
• 安装的copyright文件与上游一致，安装内容来自权威源；
• 生成的 usage 文本简洁准确；
• 同样要求刷新版本数据库、每个版本文件恰好新增一个版本。

3.3 为什么"不要自创 Checklist"

• vcpkg 的 PR 审查（尤其 AI 辅助审查）会按 .github/skills/shared/review-vcpkg-pr-guide.md 中列出的 19 条标准逐项核验。清单与审查项一一对应，自创清单会导致证据缺项或审查项与清单错位。
• x-add-version --all、SHA512、baseline 移除等条目背后都有自动化校验（仓库.github/workflows/下的check_tools_sha.yml、CodeQL.yml等流水线），清单漏填或不实会被 CI 直接拦截。

四、审查预期：maintainer 会按什么标准评审

When considering opening a pull request, note that vcpkg maintainers review contributions according to.github/skills/shared/review-vcpkg-pr-guide.md. Consult it at that stage to anticipate the evidence and package-readiness checks the review will apply; it is not required for unrelated work.

AGENTS.md 明确建议：在考虑开 PR 的阶段（而非提交后）就查阅 .github/skills/shared/review-vcpkg-pr-guide.md，以便提前准备审查所需的证据。该指南同时规定它不适用于与端口无关的工作（例如纯文档、纯构建脚本改动），避免过度流程化。

该审查指南的核心要点（供贡献者对照自检）：

• 结论形式：给出approve/approve-with-notes/request-changes/unknown四种判定之一，报告以## Summary开头并附理由。
• 代码卫生：不使用已废弃的辅助函数；新端口必须有英文description字段；无多余注释；能获取带版本号的上游归档时不得使用无版本快照。
• 支持矩阵：新端口须在库官方支持的三元组上通过 CI；"supports"字段应排除已知不兼容配置。
• 补丁审查：patch 只修复 vcpkg 特有或已提交上游的问题；源码应从官方源下载。
• 依赖确定性：端口必须确定性地消解上游探测到的每一个可选构建依赖（find_package、pkg_check_modules、option(...)、WITH_*/ENABLE_*/USE_*/BUILD_*、Mesonfeature/dependency(...)、Autotools--with-*/--enable-*等），使构建结果不依赖构建环境里已装的包；每个依赖要么无条件声明在vcpkg.json，要么显式禁用。
• 许可证与版权：vcpkg.json的许可证声明与安装内容一致；仅当许可证仅存在于头文件时，将代表性头文件直接传给vcpkg_install_copyright(FILE_LIST ...)，不得另行复制文本。
• 禁止系统修改：端口不得使用sudo、apt、brew等修改系统的应用。
• 共享脚本保护：涉及影响面大的scripts/cmake共享构建辅助改动需明确理由；存在对应vcpkg-*辅助端口时不得改动冻结的scripts/cmake助手，而应改用辅助端口。
• 链接方式：使用vcpkg_check_linkage，而非直接改动VCPKG_LIBRARY_LINKAGE。
• 行结尾：端口目录中的非 patch 文件使用 LF 行结尾；patch 文件通常 LF-only，修补 CRLF 内容时 hunk 行可含 CRLF（对应 AGENTS.md 中git diff --output的约定）。
• 集成验证（examples 深度）：新端口示例应用需在 Release 与 Debug 下验证find_package、pkg-config、以及"仅包含根<triplet>/include/并链接全部<triplet>/lib/*.lib"三种集成方式。

五、与贡献流程配套的仓库构件

要落实 AGENTS.md 的规范，需要了解仓库中与之配套的核心构件（均可直接在仓库中查阅）：

六、实操建议：一次合规的端口更新/新增流程

综合 AGENTS.md 与配套文档，可以梳理出标准操作序列：

1. 建 patch（仅当不可避免）：优先无 patch 方案；必须 patch 时用git diff --output=<ports/<name>/xxx.patch> ...生成或刷新，确保 CRLF hunk 字节无损；
2. 核对模板：打开 .github/pull_request_template.md，按改动类型取消注释对应 Checklist；
3. 逐项自检：对照审查指南 .github/skills/shared/review-vcpkg-pr-guide.md 准备证据（SHA512、supports、依赖确定性、许可证、usage 文本、集成验证等）；
4. 本地验证：在目标三元组上实际构建端口，确认PATCHES全部套用成功；
5. 同步版本数据库：运行./vcpkg x-add-version --all并提交versions/下的改动，确保每个版本文件恰好新增一个版本；
6. 提交 PR：保留模板 Checklist 区块并如实勾选，如涉及 CI 基线修复则同步移除 scripts/ci.baseline.txt 中对应条目。

七、总结

AGENTS.md用三条精炼规则锁定了 vcpkg 贡献流程中最容易出错的机械环节：patch 的字节级保真（git diff --output对抗 CRLF 丢失）、PR 清单的规范化填写（沿用官方模板而非自创）、以及审查预期的前置对齐（提交前阅读审查指南）。这三条规则分别对应仓库中的 patch 应用机制（portfile 的PATCHES字段）、PR 模板（.github/pull_request_template.md）和 AI 审查流水线（.github/skills/shared/review-vcpkg-pr-guide.md），任何一条的缺失都可能造成构建失败或审查驳回。对希望为 vcpkg 贡献端口或参与维护的开发者与 AI Agent 而言，把这三条规则内化为固定流程，是保证贡献质量的最短路径。

【免费下载链接】vcpkgC++ Library Manager for Windows, Linux, and MacOS项目地址: https://gitcode.com/GitHub_Trending/vc/vcpkg