贡献¶

Pip 的内部结构¶

我们有一个正在进行的关于 pip 内部结构的指南。当你深入研究时，它可能会有所帮助。

提交拉取请求¶

针对 main 分支提交拉取请求，并提供对您正在做什么以及原因的良好描述。您必须拥有法律许可才能分发您贡献给 pip 的任何代码，并且该代码必须在 MIT 许可下可用。

提供覆盖您更改的测试，并首先在本地运行测试。pip 支持多个 Python 版本和操作系统。任何拉取请求都必须考虑并在所有这些平台上运行。

为了便于审查，拉取请求应该很小。使它们独立，范围有限。研究表明，随着补丁大小的增加，审查质量会下降。有时，这会导致许多小的 PR 才能落地一个大型功能。特别是，拉取请求不能被视为“功能分支”，其中持续的开发工作发生在 PR 内。相反，应该将功能分解成更小的、独立的部分，这些部分可以分别进行审查和合并。

此外，避免在与您的更改无关的代码中包含“化妆品”更改，因为这些更改会使审查 PR 变得更加困难。示例包括重新调整注释或文档中的文本，或添加或删除空白行或行内的空白。如果需要，此类更改可以单独进行，作为“格式清理” PR。

自动化测试¶

所有拉取请求和合并到 'main' 分支的请求都会使用基于我们 GitHub Actions 的 .github/workflows 文件进行测试。有关 pip 持续集成的更多详细信息，请参阅 CI 文档

您可以在 GitHub 的拉取请求网页界面上找到您的 PR 的 CI 运行状态和结果。您还可以找到指向 CI 服务页面（用于特定构建）的链接，这些链接以“详细信息”链接的形式出现，以防 CI 运行失败，而您想查看输出。

要触发 CI 再次运行拉取请求，您可以关闭并打开拉取请求或向拉取请求提交另一个更改。如果需要，项目维护者可以手动触发作业/构建的重新启动。

要了解 pip 中依赖项解析周围的更广泛的软件架构，以及我们如何自动测试此功能，请参阅测试下一代 pip 依赖项解析器.

新闻条目¶

The NEWS.rst file is managed using towncrier and all non trivial changes must be accompanied by a news entry.

要向新闻文件添加条目，首先您需要创建一个问题来描述您要进行的更改。拉取请求本身可能可以作为这种功能，但最好有一个专门的问题（例如，如果 PR 最终因代码质量原因而被拒绝）。

一旦您有了问题或拉取请求，您就可以获取数字并创建一个文件，位于 news/ 目录中，以该问题数字命名，并带有与之关联的 removal、feature、bugfix 或 doc“类型”。

如果您的问题或 PR 编号是 1234 并且此更改正在修复一个错误，那么您将创建一个名为 news/1234.bugfix.rst 的文件。PR 可以通过创建多个文件来跨越多个类别（例如，如果您添加了一个功能并弃用了/删除了旧功能，您将创建 news/NNNN.feature.rst 和 news/NNNN.removal.rst）。

如果一个 PR 涉及多个问题/PR，您可以为每个问题创建一个具有完全相同内容的文件，Towncrier 将对其进行重复数据删除。

新闻条目内容¶

该文件的内容是 reStructuredText 格式的文本，将用作新闻文件条目的内容。您不需要在条目中引用问题或 PR 编号，因为 towncrier 会在渲染新闻文件时自动添加对所有受影响问题的引用。文件末尾必须有一个换行符。

为了在 NEWS.rst 文件中保持一致的风格，最好使新闻条目简洁明了，使用句子大小写，小于 80 个字符，并使用祈使语气 - 条目应完成句子“此更改将...”。在罕见的情况下，如果一行不够，请使用祈使语气中的摘要行，并用空白行将其与一个或多个段落中对功能/更改的描述隔开，每个段落都包装在 80 个字符处。请记住，新闻条目是为了最终用户设计的，并且应该只包含与最终用户相关的详细信息。

选择新闻条目的类型¶

一个微不足道的更改是任何不值得在新闻文件中添加条目的更改。一些示例包括：对公众而言没有任何改变的代码重构、拼写错误修复、空白修改等。要将 PR 标记为微不足道，贡献者只需在 news/ 目录中添加一个随机命名的空文件，扩展名为 .trivial.rst。如果您使用的是类似 POSIX 的操作系统，则可以通过运行 touch news/$(uuidgen).trivial.rst 来添加一个。在 Windows 上，可以使用 New-Item "news/$([guid]::NewGuid()).trivial.rst" 在 Powershell 中实现相同的结果。核心提交者还可以向 PR 添加“跳过新闻”标签，这将实现相同的效果。

升级、删除或添加一个新的供应商库会使用 news/<library>.vendor.rst 文件进行特别说明。这除了拉入该库可能具有的任何功能、错误修复或其他类型的新闻之外。这使用库名称作为键，因此两次更新同一个库不会产生两个新闻文件条目。

对进程、策略或其他非代码相关的更改，这些更改值得注意，可以使用 news/<name>.process.rst 文件进行。这通常不用于此，但可以用于更改版本方案、更新弃用策略等。

更新您的分支¶

在您工作时，您可能需要将您的本地 main 分支更新到主 pip 仓库中的 main 分支，该分支会随着维护者合并拉取请求而向前推进。大多数参与项目的人使用以下工作流程。

这假设您已将 Git 配置为，当您运行以下命令时

git remote -v

您的输出看起来像这样

origin  https://github.com/USERNAME/pip.git (fetch)
origin  https://github.com/USERNAME/pip.git (push)
upstream  https://github.com/pypa/pip.git (fetch)
upstream  https://github.com/pypa/pip.git (push)

在上面的示例中，USERNAME 是您在 GitHub 上的用户名。

首先，从主 pip 仓库中获取最新更改，upstream

git fetch upstream

然后，检出您的本地 main 分支，并在其基础上重新设置更改

git checkout main
git rebase upstream/main

此时，您可能需要解决合并冲突。完成此操作后，将您刚刚对本地 main 分支所做的更新推送到 GitHub 上的 origin 仓库。

git checkout main
git push origin main

现在，您的本地 main 分支和 origin 仓库中的 main 分支已经更新了来自 pip 主仓库的最新更改。

要保持您的分支更新，流程类似。

git checkout awesome-feature
git fetch upstream
git rebase upstream/main

现在，您的分支已经更新了来自上游 pip 仓库 main 分支的最新更改。

在您处理分支时，将它们推送到 GitHub 上的 origin 备份是个好习惯。要推送分支，运行以下命令

git push origin awesome-feature

在本例中，<awesome-feature> 是您的分支名称。这将把您正在处理的分支推送到 GitHub，但不会创建 PR。

将您的分支推送到 origin 后，如果需要再次更新它，您需要通过运行以下命令强制推送您的更改

git push -f origin awesome-feature

push 后的 -f（或 --force）标志强制从本地分支更新到 origin 分支。如果您的分支上有一个打开的 PR，强制推送将更新您的 PR。（当有人在 PR 上请求更改时，这是一个有用的命令。）

如果您收到类似于这样的错误消息

! [rejected]        awesome-feature -> awesome-feature (non-fast-forward)
error: failed to push some refs to 'https://github.com/USERNAME/pip.git'
hint: Updates were rejected because the tip of your current branch is behind
hint: its remote counterpart. Integrate the remote changes (e.g.
hint: 'git pull ...') before pushing again.
hint: See the 'Note about fast-forwards' in 'git push --help' for details.

尝试使用 push -f 强制推送您的分支。

pip 主仓库中的 main 分支会经常更新，因此您可能需要在处理分支时至少更新一次您的分支。

感谢您的贡献！

成为维护者¶

如果您想成为正式的维护者，请从提供帮助开始。

作为第一步，我们欢迎您对 pip 的问题跟踪器进行问题分类。pip 维护者会在贡献者贡献一段时间（可能至少 2-3 个月）并积极为项目做出贡献后，向他们提供分类权限。这对于成为 pip 维护者是可选的，并且强烈建议。

稍后，当您认为自己已经准备好了（可能在开始分类后至少 5 个月），请与一位维护者联系，他们将发起现有维护者之间的投票。

注意

成为维护者后，应该授予一个人访问多个平台上各种 pip 相关工具的权限。这些内容记录在此处，以便维护者将来参考

GitHub 推送访问权限
PyPI 发布访问权限
CI 管理功能
ReadTheDocs 管理功能