如何向vcpkg提交一个PR

为 vcpkg 提交 Pull Request 的操作步骤

如果你想为 vcpkg 提交一个 pull request，可以通过以下操作步骤来完成，以更新 port 为例：

1. 访问 vcpkg 的官网：microsoft/vcpkg: C++ Library Manager for Windows, Linux, and MacOS (github.com)，点击 Fork 按钮来创建一个位于你账户下的 vcpkg 仓库副本。

2. 将你 Fork 的 vcpkg 副本克隆到本地：

git clone https://github.com/MonicaLiu0311/vcpkg.git

3. 将 microsoft/vcpkg 添加为上游仓库：

git remote add upstream https://github.com/microsoft/vcpkg.git

4. 获取 microsoft/vcpkg 的更新信息：

git remote update upstream

5. 同步 microsoft/vcpkg 最新的内容到你的本地仓库。

有两种方式，一种是访问你的 vcpkg 仓库，手动点击按钮 Sync fork 来同步，然后在你本地 vcpkg 仓库的 master 分支下运行命令 git pull 即可：

另一种是直接运行 git pull upstream master 命令：

6. 设置配置你本地 git 的操作人名字和邮箱：

git config --global user.name "xxx"

git config --global user.email "xxxxxx.com"

7. 在本地创建一个新的 git 分支（分支的名称不和其他分支重复即可，一般为你的 fix 内容，比如 fix_xxx/update_xxx）：

git checkout -b "Dev/xxx/update_xxx"

8. 在本地修改相关代码，push 到 origin：

9. 创建一个 pull request：

• 点击 compare & pull request 按钮开始创建流程：

• 请仔细阅读 pull request 模板，并根据需求正确填写：

根据需求填写 PR 的模板，一般有以下两种情况：

①对 port 修复或更新：
<!-- 如果您的 PR 修复了 issue，请在这里注明，每个已修复的问题都单独一行，并在每行前面添加 "Fixes #NNNNNN." -->
<!-- 如果您仍在进行 PR 的工作，请将其标记为草稿：https://github.blog/2019-02-14-introducing-draft-pull-requests/ -->
<!-- 如果此 PR 更新了现有的 port，请取消注释并填写以下 checklist：

- [ ] 更改符合 [维护指南](https://github.com/microsoft/vcpkg-docs/blob/main/vcpkg/contributing/maintainer-guide.md) 。
      • 在做更改前，请阅读 vcpkg 的维护指南，理解我们的项目要求，减少错误和冲突。

- [ ] 对于每个更新的下载，SHA512 都已更新。
      • 为了确保软件包的完整性，请将从官方来源或版本控制系统中获得的 SHA512 更新到 [VCPKG_ROOT]/ports/portName/portfile.cmake 中。
      
- [ ] "supports" 条款反映了此新版本可能支持的平台。
      • 它提供了有关此软件包版本可能在哪些操作系统和体系结构上正常工作的信息，例如："supports": "!android & !xbox"。
      
- [ ] 从 [CI baseline](https://github.com/microsoft/vcpkg/blob/master/scripts/ci.baseline.txt) 文件中删除任何已修复的条目。
		• ci.baseline.txt 文件定义 CI Pipeline 中 port 的当前预期构建状态。
		• 当某个构建问题被修复后，相应的条目应该从 ci.baseline.txt 删除，删除已修复的条目意味着该问题已经得到解决，不再影响 CI Pipeline 的构建和测试。
		
- [ ] 从 port 的目录中删除任何不再应用的补丁文件。
		• 删除 [VCPKG_ROOT]/ports/portName/ 目录下不再适用的补丁文件，同时删除 portfile.cmake 中应用的部分。
		
- [ ] 通过重新运行 `./vcpkg x-add-version --all` 并提交结果，修复了版本数据库。
		•  vcpkg 中的版本数据是根据 git commit 信息生成的，所以每次必须在提交修改文件之后再运行 x-add-version 命令。
		• 首次运行 `./vcpkg x-add-version portName` 命令会生成版本数据，具体的数据在 [VCPKG_ROOT]/versions/baseline.json 和 [VCPKG_ROOT]/versions/p-/portName.json 中，[VCPKG_ROOT] 是你的本地 VCPKG 路径。
		• 第一次运行之后，已经有了版本数据，后续如果还有其他修改，只需 `./vcpkg x-add-version portName --overwrite-version` 命令更新 portName.json 中的 git-tree 即可。

- [ ] 在修改后的每个 port 的 versions 文件中，只添加了一个版本。
		• 在您生成版本数据后，baseline.json 中的版本数据会进行更新替换；而 portName.json 中会新增一个 json 对象，但是只能新增一个。

NEW PORT CHECKLIST 结束（删除此行）-->

②添加一个 new port：
<!-- 如果此 PR 添加了一个新的 port，请取消注释并填写以下 checklist：
- [ ] 更改符合 [维护指南](https://github.com/microsoft/vcpkg-docs/blob/main/vcpkg/contributing/maintainer-guide.md)
		• 在做更改前，请阅读 vcpkg 的维护指南，理解我们的项目要求，减少错误和冲突。

- [ ] port 的名称与 https://repology.org/ 上的现有组件名称（如果有）匹配，和/或在搜索引擎上与该组件强相关。
		• repology 是一个用于跟踪和比较不同发行版软件包的工具，使用该网站上已有的相同名称有助于确保一致性和识别性。
		• 在为 vcpkg 创建一个新的库时，应尽量选择一个已经在 repology 上存在的相同名称，例如：icu、zlib。
		• 为了进一步增强识别性，也可以匹配搜索引擎上与该库强相关的名称。

- [ ] 可选依赖项以精确的方式解析。例如，如果组件使用 CMake 构建，所有 `find_package` 调用都是 REQUIRED 的，满足 `vcpkg.json` 声明的依赖，或者通过 [CMAKE_DISABLE_FIND_PACKAGE_Xxx](https://cmake.org/cmake/help/latest/variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName.html) 禁用。
		• 可选依赖项：有时一个库可能依赖于其他库才能正常工作，这些依赖项被称为可选依赖项，它们不是组件的必需条件，但在某些情况下可能会提供额外的功能。
		• REQUIRED：在 CMake 中，REQUIRED 是一个参数，用于指示 find_package 命令，如果找不到指定的依赖项，构建过程应该失败。
		• CMAKE_DISABLE_FIND_PACKAGE_Xxx：这是 CMake 提供的一个机制，用于禁用特定的 find_package 调用，可以使用它来阻止 CMake 查找和定位名为 Xxx 的依赖项，从而确保不会解析或使用某些可选依赖项。
		• 在 vcpkg.json 中，dependencies[] 用于声明必需依赖项，确保库的必需依赖被解析和配置；而 features{} 则用于配置构建选项和特定的依赖解析方式，以满足特定的需求。

- [ ] `vcpkg.json` 中的版本号与上游一致。
		• 确保 vcpkg.json 文件中的 "version" 字段与上游软件包的版本号保持一致，告知 vcpkg 用户上游原始源提供的版本。

- [ ] `vcpkg.json` 中的许可证声明与上游一致。
		• 确保 vcpkg.json 文件中的 "license" 字段与上游软件包的许可证声明保持一致，确保 vcpkg 用户在使用和分发软件包时遵守上游软件包的许可条件。

- [ ] 安装的组件的源代码来自权威来源。
		• 确保从官方网站、版本控制库（如 GitHub）、开发者社区等获取源代码。
		• 下载的文件可以通过校验哈希值（如 SHA-256）与官方提供的哈希值进行比对，以确保文件完整性和一致性。
		• 官方或权威来源通常会提供技术支持、文档和更新，有助于更好地了解和维护所使用的组件，以及在需要时获得修复和改进。

- [ ] 生成的 "usage text" 是准确的。有关上下文，请参见 [adding-usage](https://github.com/microsoft/vcpkg-docs/blob/main/vcpkg/examples/adding-usage.md)。
		• 确保生成的 "usage text" 准确无误，可以帮助 vcpkg 用户更轻松地使用安装的软件包，并确保构建系统能够正确地配置和链接软件包。

- [ ] 通过重新运行 `./vcpkg x-add-version --all` 并提交结果，生成版本数据。
		•  vcpkg 中的版本数据是根据 git commit 信息生成的，所以每次必须在提交修改文件之后再运行 x-add-version 命令。
		• 首次运行 `./vcpkg x-add-version portName`  命令会生成版本数据，具体包括 [VCPKG_ROOT]/versions/baseline.json 和 [VCPKG_ROOT]/versions/p-/portName.json，[VCPKG_ROOT] 是你的本地 VCPKG 路径。
		• 第一次运行之后，已经有了版本数据，后续如果还有其他修改，提交之后，只需再 `./vcpkg x-add-version portName --overwrite-version`  命令更新 portName.json 中的 git-tree 即可。

- [ ] 在新 port 的 versions 文件中，只添加了一个版本。
		• 对于一个新的 port，在您运行 x-add-version 命令生成版本数据后，baseline.json 中会新增一个以 portName 命名的版本数据对象。

- [ ] 在修改后的每个 port 的 versions 文件中，只添加了一个版本。
		• 在您运行 x-add-version 命令生成版本数据后，portName.json 中会新增一个 json 对象，但是只能新增一个。
NEW PORT CHECKLIST 结束（删除此行）-->

注意 Merge 的过程是从 Fork 后的副本仓库到 microsoft/vcpkg ，标题的格式一般是 <port name> specific behavior。如下图所示，填写完毕后请点击 Draft pull request 提交：

等待 CI Pipeline 运行通过后，点击 Ready for review 提醒 vcpkg 团队进行审查：