用于计算分子生物学的 Python 工具
用于计算分子生物学的 Python 工具
这些是使用 git 进行 Biopython 开发的（草案）一般指南。我们仍在完善细节等。
本文档旨在概述 Biopython 的开发方式。它应该包括所有必要的技术信息以及典型流程和使用场景。它应该对核心开发人员、潜在的代码贡献者、测试人员以及所有对 Biopython 代码感兴趣的人有所帮助。
此版本是非正式草案，可能会更改。
如果你只想从我们的存储库中获取最新的（尚未正式发布的）Biopython，请参阅我们的 源代码页面。此页面是关于实际使用 git 来跟踪更改的。
如果你发现 Biopython 存在问题，并且认为你知道如何修复它，那么我们建议你遵循简单的路线，提交一个错误并描述你的修复。理想情况下，你应该上传一个补丁文件，显示 Biopython 最新版本（来自我们的存储库）和你修改后的版本之间的差异。使用命令行工具 diff 和 patch 是一个非常有用的技能，并且几乎是使用版本控制系统的先决条件。
除非你打算进行简单的单次贡献之外的贡献，否则你不应该费心创建自己的 git 分支。
本节介绍有关 git 使用的详细介绍，包括所需的软件以及与 Github 的集成。如果你想开始为 Biopython 贡献代码，你绝对需要安装 git 并学习如何获取 Biopython 的分支。如果你想与他人轻松分享你的更改，你还应该注册一个 Github 帐户并阅读手册中相应的部分。最后，如果你参与了对实验性 Biopython 模块的合作之一，你还应该了解代码审查和分支合并。
你需要在你的计算机上安装 Git。 Git 可用于所有主要操作系统。请使用下面描述的适当安装方法。
Git 现在已打包到所有主要 Linux 发行版中，你应该在你的软件包管理器中找到它。
你可以从 git-core 包中安装 Git。例如，
sudo apt-get install git-core
你可能还想安装以下包：gitk、git-gui 和 git-doc
git 也打包在基于 rpm 的 Linux 发行版中。
yum install gitk
应该可以在任何最近的 fedora/mandriva 或衍生产品中为你完成这项工作
从 http://code.google.com/p/git-osx-installer/ 下载 .dmg 磁盘镜像
从 Windows 安装程序 下载官方安装程序
如果你的安装成功，你应该能够运行
git --help
在控制台窗口中获取有关 git 使用的信息。如果这失败了，你应该参考 git 的 文档 进行故障排除。
在你的机器上安装 Git 后，你可以获取代码并开始开发。但是，由于代码托管在 GitHub 上，你可能希望通过注册一个 GitHub 帐户来利用该网站提供的功能。虽然 GitHub 帐户完全是可选的，并且不需要获取 Biopython 代码或参与开发，但 GitHub 帐户将使所有其他 Biopython 开发人员能够跟踪（和审查）你对代码库的更改，并将帮助你跟踪其他开发人员的贡献。这为 Biopython 社区营造了一个社交的协作环境。
如果你还没有 GitHub 帐户，你可以在 此处 创建一个。创建帐户后，通过单击登录后的“SSH 和 GPG 密钥”来上传 SSH 公钥。有关生成和上传 SSH 公钥的更多信息，请参阅 本 GitHub 指南。
为了开始使用 Biopython 源代码，你需要获取我们 git 存储库的本地克隆。在 git 中，这意味着你实际上会获得我们 git 存储库的完整克隆，以及完整的版本历史记录。由于压缩，这与单个树副本的大小相差不大，但你需要在磁盘空间方面接受一小部分开销。
大致来说，有两种方法可以将源代码树放到你的机器上：简单地“克隆”存储库，或者在 GitHub 上“分支”存储库。它们并没有太大区别，实际上两种方法都会在你的机器上生成一个包含存储库完整副本的目录。但是，如果你有 GitHub 帐户，你可以使你的存储库成为项目的公共分支。如果你这样做，其他人将能够轻松地审查你的代码，从你的代码创建自己的分支或将其合并回主干。
使用 Github 上的分支是进行 Biopython 新功能的首选方法，因此即使你认为你的更改不是立即包含在 Biopython 的主干中，学习它并使用它也是有用的。但即使你决定不使用 github，你也可以随时稍后更改它（使用你的分支中的 .git/config 文件）。为简单起见，我们将分别描述这两种可能性。
获取存储库副本（在 Git 术语中称为“克隆”）而无需 GitHub 帐户非常简单
git clone https://github.com/biopython/biopython.git
cd biopython
此命令将在你的机器上创建整个 Biopython 存储库的本地副本（你自己的官方存储库的个人副本，包含其完整历史记录）。你现在可以进行本地更改并将它们提交到此本地副本（虽然我们建议你为此使用命名分支，并将 master 分支与官方 Biopython 代码保持同步）。
但是，如果你希望其他人看到你的更改，则必须将你的存储库发布到公共服务器（例如，在 GitHub 上）。
如果你已登录 GitHub，则可以转到 Biopython 存储库页面
https://github.com/biopython/biopython/tree/master
并单击名为“分支”的按钮。这将创建一个官方 Biopython 存储库的分支（基本上是一个副本），可以在 GitHub 上公开查看，但列在你的个人帐户下。它应该在类似以下 URL 的 URL 下可见
https://github.com/yourusername/biopython
由于你的新 Biopython 存储库是公开可见的，因此更改描述和主页字段以使其更有意义（即与从官方存储库复制的字段不同）被认为是良好的做法。
如果你还没有这样做，请设置 SSH 密钥并 将其上传到 github 进行身份验证。
现在，假设你在你的计算机上安装了 git，请在你的机器上本地执行以下命令。此“url”在你的存储库的 GitHub 页面上给出（如果你已登录）
git clone [email protected]:yourusername/biopython.git
cd biopython
其中 yourusername 自然地代表你的 GitHub 用户名。你刚刚在你的机器上创建了 Biopython 存储库的本地副本。
你可能还想将你的分支链接到官方发行版（请参阅以下内容，了解如何使你的副本保持同步）
git remote add upstream https://github.com/biopython/biopython.git
要向你的 GitHub 存储库添加其他贡献者（即你希望能够向其提交代码的人员），请选择“编辑”，然后将他们添加到“存储库合作者”部分。你需要知道他们在 GitHub 上的用户名。
如果你还没有这样做，请告诉 git 你的姓名以及你在 GitHub 上使用的电子邮件地址（这样你的提交就会与你的 GitHub 帐户匹配）。例如，
git config --global user.name "David Jones"
git config --global user.email "[email protected]"
Biopython 尝试遵循 PEP8 和 PEP257 中规定的编码约定。
在开始编写代码之前，我们要求你安装一些用于自动检查的工具。这包括一个 git pre-commit 钩子，因此你的每次提交（见下文）都会自动检查 Biopython 同意编码风格的违规行为。具有违规行为的提交将被阻止。因此，你确保稍后提交到 Biopython（一个拉取请求，见下文）不会被我们自动的在线风格检查阻止。
pip install pre-commit
pre-commit install # in biopython directory
有关更多信息，请参阅 CONTRIBUTING.rst 文件。
现在，你可以对你的本地存储库进行更改 - 你可以在脱机状态下执行此操作，并且可以根据需要频繁地提交更改。事实上，你应该尽可能频繁地提交，因为更小的提交更容易管理和记录。
首先，创建一个新的分支来进行一些更改，并切换到该分支
git branch demo-branch
git checkout demo-branch
要检查你在哪个分支上，请使用
git branch
假设你已经对文件 Bio/x.py 进行了更改。试试这个
git status
因此，要提交此更改，你首先需要显式地将此文件添加到你的更改集中
git add Bio/x.py
现在你提交了
git commit -m "added feature Y in Bio.x"
你在 Git 中的提交是本地的，即它们只影响你的计算机上的工作分支，而不是整个 Biopython 树，甚至不是你 GitHub 上的分支。你不需要互联网连接即可提交，因此你可以非常频繁地执行此操作。
如果你使用 Github，并且正在处理你自己的分支的克隆，你可以非常轻松地让你的更改供其他人使用。
当你认为你的更改稳定并且应该由其他人审查时，你可以将你的更改推送到 GitHub 服务器
git push origin demo-branch
如果你直接从官方 Biopython 分支克隆，则此操作无效，因为只有核心开发人员才能访问主存储库的写入权限。
我们建议你实际上不要对本地存储库（或你在 github 上的分支）中的**master** 分支进行任何更改。相反，使用命名分支来执行你自己的任何工作。这种方法的优点是可以轻松地将上游**master**（即官方 Biopython 分支）拉取到你的存储库。
假设你已经执行了此命令（你只需要执行一次）
git remote add upstream https://github.com/biopython/biopython.git
那么你只需要
git checkout master
git pull upstream master
如果你从未对本地**master** 分支进行过任何提交，那么这应该始终是一个简单的快进合并，没有任何冲突。然后，你可以处理将上游更改从你的本地 master 分支合并到你的本地分支（并且你可以在脱机状态下执行此操作）。
如果你在网上托管了你的存储库（例如，在 github 上），那么将更新的 master 分支推送到那里
git push origin master
如果你认为你的更改值得包含在主 Biopython 发行版中，那么在我们的错误跟踪器上提交一个（增强）错误，并包含一个指向你更新的分支的链接（即你在 GitHub 上的分支，或另一个公共 Git 服务器）。你也可以将一个补丁附加到错误。如果更改被接受，Biopython 开发人员之一将不得不将此代码检查到我们的主存储库中。
在 GitHub 本身，你可以通过从你的分支的主页发送一个“拉取请求”来告知主分支的维护者你的更改。将文件提交到主分支后，你可能希望删除你不再需要的错误修复分支。可以通过选择“编辑”，然后从编辑页面的底部选择“删除存储库”来删除分支。
如果您在开始工作后发生了其他事情，则应用到官方存储库的 master 分支时可能需要合并。在这种情况下，我们可能会要求您通过变基您的工作来提供帮助。
git fetch upstream
git checkout demo-branch
git rebase upstream/master
希望您分支与官方存储库的 master 分支之间的唯一更改是微不足道的，并且 git 会自动处理所有事情。如果不是，您将不得不手动处理冲突。如果这有效，您可以通过替换现有的（变基前）分支来更新拉取请求。
git push origin demo-branch --force
但是，如果变基不顺利，请使用以下命令放弃（希望 Biopython 开发人员可以为您解决变基或合并）
git rebase --abort
由于 git 是一个完全分布式的版本控制系统，因此任何人都可以集成来自其他人的更改，假设他们使用的是源自共同根的分支。这对致力于新功能并希望接受来自其他人的贡献的人特别有用。
本节将特别针对 Biopython 核心开发者或接受分支更改的任何人。
例如，假设 Eric 在他的公共存储库中有一些有趣的更改
https://github.com/etal/biopython.git
您必须通过创建对该远程存储库的引用来告诉 git 关于这一点
git remote add eric https://github.com/etal/biopython.git
现在我们可以使用一行代码获取 Eric 的所有公共存储库
git fetch eric
remote: Counting objects: 138, done.
remote: Compressing objects: 100% (105/105), done.
remote: Total 105 (delta 77), reused 0 (delta 0)
Receiving objects: 100% (105/105), 27.53 KiB, done.
Resolving deltas: 100% (77/77), completed with 24 local objects.
From https://github.com/etal/biopython
* [new branch] bug2754 -> eric/bug2754
* [new branch] master -> eric/master
* [new branch] pdbtidy -> eric/pdbtidy
* [new branch] phyloxml -> eric/phyloxml
现在，我们可以运行您自己的任何分支与 Eric 的任何分支之间的差异。您可以使用以下命令列出您自己的分支
git branch
* master
...
请记住，星号显示当前签出的分支。
要列出您已设置的远程分支
git branch -r
eric/bug2754
eric/master
eric/pdbtidy
eric/phyloxml
upstream/master
origin/HEAD
origin/master
...
例如，要显示您的 **master** 分支与 Eric 的 **master** 分支之间的差异
git diff master eric/master
...
如果您都将您的 **master** 分支与上游 Biopython 存储库同步，那么他的 **master** 分支将不会很有趣。相反，试试
git diff master eric/pdbtidy
...
您现在可能希望将 Eric 的更改（部分）合并到您的本地存储库中的新分支中。要复制您的本地存储库中的分支（例如 pdbtidy），请键入
git checkout --track eric/pdbtidy
如果 Eric 在他的远程分支中添加了更多提交，并且您想更新您的本地副本，只需执行
git checkout pdbtidy # if you are not already in branch pdbtidy
git pull
如果您以后想删除对该特定分支的引用
git branch -r -d eric/pdbtidy
Deleted remote branch eric/pdbtidy (79b5974)
或者，要删除对 Eric 所有分支的引用
git remote rm eric
git branch -r
upstream/master
origin/HEAD
origin/master
...
或者，在 GitHub 中，您可以使用 fork-queue 从其他人的 fork 分支中 cherry-pick 提交。有关详细信息，请参阅 这篇文章。虽然这默认会将更改应用于您的当前分支，但您通常会使用新的集成分支来执行此操作，然后将其提取到您的本地计算机以测试所有内容，然后再将其合并到您的主分支。
本节面向 Biopython 开发人员，他们被允许将更改提交到 Biopython 主“官方”分支。它描述了典型活动，例如合并来自 git 分支和补丁文件的贡献代码更改。
目前，Biopython 主分支托管在 github 上。要更改主分支，您需要一个 GitHub 帐户，并且需要被添加为 Biopython 帐户的协作者。这只需要做一次。如果您有 GitHub 帐户，但还不是协作者，并且您认为您应该是（例如，您在 open-bio 服务器上拥有 cvs 帐户）：请 Peter 将您添加进去（这是针对定期贡献者的，因此如果您只有一个更改要进行，请考虑通过其中一位开发者提交您的更改）。
成为协作者后，您可以使用私有 URL 拉取 Biopython 官方分支。如果您想创建一个新存储库（链接到主分支），您可以直接克隆它
git clone [email protected]:biopython/biopython.git
它将在“biopython”目录中创建一个包含官方分支的本地副本。它还会将“origin”设置为 GitHub 副本。这是推荐的方式（至少对于开始而言），因为它最大限度地降低了意外将更改推送到官方 GitHub 分支的风险。
或者，如果您已经有一个有效的 git 存储库（包含您的分支和您自己的更改），您可以使用 git “remote 命令”添加指向官方分支的链接……但我们在这里不会介绍它。
在以下部分中，我们假设您已遵循推荐的方案，并且您的 .git/config 文件中有以下条目
[remote "origin"]
url = [email protected]:biopython/biopython.git
[branch "master"]
remote = origin
如果您从补丁提交，也很容易。首先确保您已更新到官方分支
git checkout master
git pull origin
然后进行更改，即应用补丁
patch -r someones_cool_feature.diff
如果您看到树中添加了一些文件，请将其添加到 git
git add Bio/Tests/some_new_file
然后进行提交（在添加文件后）
git commit -a -m "committed a patch from a kind contributor adding feature X"
提交更改后，您可以推送到 github
git push origin
假设您要合并某人已提交到某个 git 存储库的更改，该存储库在某个时候从官方 Biopython 分支克隆。他需要通过提供一个 URL 来使他的存储库对您可用（只读）。通常，这将位于 GitHub 上（但可能是任何公共 git url）。让我们假设 url 是（恰好是我的 Biopython 克隆）
https://github.com/barwil/biopython.git
首先，您需要从该存储库获取代码
git remote add Bartek https://github.com/barwil/biopython.git
git fetch Bartek
然后您可以查看有哪些分支
git branch -r
Bartek/master
Bartek/motif_docs
Bartek/test-branch
假设您要合并来自 test-branch 的更改。您需要确保您已更新到官方分支
git checkout master
git pull origin
然后，您可以进行实际的合并
git pull Bartek test-branch
并且（假设您对 git diff 和 git status 的结果感到满意），您可以推送到 GitHub 上的公共存储库（请勿尝试使用此示例数据进行尝试）
git push origin
完成后，您可以删除对远程存储库的引用
git remote rm Bartek
如果您想在当前 Biopython 官方分支上添加标签（通常这是为了标记新的版本），您需要遵循以下步骤
首先确保您已更新到官方分支
git checkout master
git pull origin
然后添加实际标签
git tag new_release
并将其推送到 github
git push --tags origin master
网络上有很多关于使用 Git 的优秀指南