Python Pip 基础教程 -参与 Pip 开发指南

Pip 开发团队资源还是蛮紧张的，如果你有多余的时间，如果你对 Pip 开发有兴趣，可以参与进来，本章节，我们将介绍如何参与 Pip 的开发

本章节我们介绍的方法不仅仅适用于参与 Pip 开发，也适用于参与所有开源项目的开发

拉取请求 ( Pull Requests )

参与开源项目开发的三大步:

向主分支提交 Pull 请求
提供一个关于你正在做的事情和原因的良好描述
提供涵盖你的更改的测试，并尝试首先在本地运行测试

例如，假设你已经拥有了 GitHub 账号，且已经从 https://github.com/pypa/pip 拉取了 Pip 代码并创建了自己的仓库 ( fork 功能 ) ，同时假设你自己的仓库地址为 https://github.com/yourname/pip

上面这些流程，如果使用 Git 命令则如下

$ git clone git@github.com:pypa/pip.git
$ cd pip
# ...
$ git diff
$ git add <modified> ...
$ git status
$ git commit

你可以在提交消息中添加 GitHub 问题链接 ( 如 #1259 ) 来引用相关问题，并添加一些短语，如「修复 #1259 」，提交成功后，甚至可以自动关闭相关问题

接着，将更改提交到你自己 fork 的仓库

$ git push git@github.com:yourname/pip.git

最后，在 https://github.com/yourname/pip/pulls 仓库中打开拉取请求页面，然后点击「拉取新请求 ( New pull request ) 」

这里，就成功结束了

自动化测试

所有拉取请求和合并到「主」分支的代码都会根据我们的 .travis.yml 文件在 Travis 中进行测试

通常，拉取的请求中会显示指向特定 travis 构建的链接，如果没有，你可以在我们的 travis pull requests 页面上找到它

触发 Travis 再次运行拉取请求的唯一方法是向拉分支提交另一个更改

我们还有 Jenkins CI，用于定期构建可以在 Windows 和 centos 操作系统上适配某些 Python 版本的发行版本

运行测试

操作系统要求：subversion ，bazaar，git 和 mercurial

Python 第三方包依赖：tox 或 pytest，virtualenv，scripttest和 mock

在本地运行测试的方法：

$ tox -e py33           # 运行测试的首选方法，可以使用 pyNN 在指定的版本中运行，
                        # 或者使用 -e 在所有的版本上运行
$ python setup.py test  # 使用 setuptools 测试插件
$ py.test               # 直接使用 py.test
$ tox                   # Using tox against pip's tox.ini

如果你缺少 VCS 中的某些工具，可以告诉 py.test 跳过它

$ py.test -k 'not bzr'
$ py.test -k 'not svn'

加入开发

pip 项目欢迎各位的加盟，具体来说，你可以通过以下方式参与和帮助 pip 开发

创建一个拉取请求 ( Pull Requests ) 用于编码，测试或撰写文档
对于未解决的问题进行回复和创建一个拉取请求
在邮件组中帮忙回复问题

如果你想要成为一名官方维护者，那么首先，你必须先做一些简单的帮忙

然后，当你认为自己已经准备就绪时，请与其中一位维护人员联系，他们将进行投票

添加新闻条目

NEW.rst 文件使用 towncrier 来管理，且所有重要的变更都必须附有新闻条目

要向新闻文件添加条目，首先必须存在一个描述要进行的更改的问题 ( issue )

拉取请求本身可以提供一个这样的描述，但应该优先使用一个专有的问题 ( issue ) ( 例如，在由于代码质量原因导致 PR 被拒绝的情况下 )

一旦拥有了问题或拉取请求，我们就可以获取该问题或请求的编号并在 news/ 目录中创建一个文件，该文件以编号为名，并使用removal, feature, bugfix 或 doc 作为扩展名

也就是说，如果我们的问题或 PR 编号是 1234 并且此次更改主要用于修复 bug ，那么我们将创建一个文件 news/1234.bugfix

一个 PR 可以通过创建多个文件来跨越多个类别，例如，如果我们添加了一项功能并同时弃用/删除了旧功能，则可以创建 news/NNNN.feature 和 news/NNNN.removal

同样，如果某个 PR 涉及多个问题 / PR，我们可以为每个问题创建一个具有完全相同内容的文件，Towncrier 会自动将重复数据删除

新闻文件条目的内容的使用 reStructuredText 格式，我们无需在此处引用问题或 PR 编号，因为在显示新闻文件时，towncrier 会自动添加对所有受影响问题的引用

一些细微的变更可能并不会在新闻文件中作为条目列出，例如代码重构，对公众而言不会改变任何东西，错误修正，空白修改等。对于细微的问题而提交的 PR，贡献者只需要将一个随机命名的扩展名为 .trivial 的空文件添加到news/ 目录中，如果你使用的是 POSIX 操作系统，可以通过运行 touch news/$(uuidgen).trivial 命令添加一个。核心提交者还可以向 PR 添加「细微」标签用于完成同样的事情

使用一个 news/<library>.vendor 文件来更新、移除或添加一个特别值得一提的依赖库，这是此库中可能包含的任何功能，bug 修正或其它类型的新闻的补充，我们使用库名作为文件名可以防止两次更新同一个库不会产生两个新闻文件条目

发布步骤

在当前的 pip 主分支上，通过运行命令 invoke generate.authors 创建一个新的 AUTHORS.txt 文件，然后把新创建的文件加入 git 并提交
在当前的 pip 主分支上，创建一个新的提交，包括修改 pip/__init__.py 中的版本为当前要发布的版本，并更新 CHANGES.txt 文件以反映当前的修改，然后提交所有文件
在当前的 pip 主分支上，通过运行命令 invoke generate.news 创建一个新的 NEWS.rst，然后提交所有文件
在当前的 pip 主分支上，使用命令 git tag -s X.Y.Z 创建一个名称为 X.Y.Z 的命名标签
使用命令 git checkout X.Y.Z 迁出标签 X.Y.Z，然后使用命令 python setup.pysdist bdist_wheel 创建发行版本
使用 twine 命令 twine upload -s dist/* 将刚刚创建的发行版本上传到 PiPY，上传的文件还应该包括分发文件的 GPG 签名
推送所有的更改
在 get-pip 仓库中使用命令 invoke generate.installer 重新生成 get-pip.py 文件，并提交所有变更

创建一个 bug 修复版本

有时我们需要发布 X.Y.Z+1 形式的 bug 修复版本，为了创建这样的修复版本，修复的代码必须应该已经合并到主分支中

然后，根据下面的步骤创建一个 bug 修复版本

使用 Git 命令 git checkout -brelease/X.Y.Z+1 X.Y.Z 创建一个名为 release/X.Y.Z+1 的分支并打上 X.Y.Z 标签
Cherry 从主分支中挑选出修复问题的提交，修复冲突并将更改日志条目从开发版本的 changelog 部分移动到 X.Y.Z+1 部分
把 release/X.Y.Z+1 分支提交到 GitHub ，并提交一个到主分支的 PR 然后等待最后的测试
一旦测试通过，将 release/X.Y.Z+1 分支的代码合并到主分支，并从上面发布流程中的第四步开始创建一个新的修复版本