用於計算分子生物學的 Python 工具
用於計算分子生物學的 Python 工具
這些是使用 Git 進行 Biopython 開發的（草案）一般準則。我們仍在處理更精細的細節等等。
本文檔旨在概述 Biopython 的開發方式。它應包含所有必要的技術資訊，以及典型的流程和使用場景。它應該對核心開發人員、潛在的程式碼貢獻者、測試人員以及所有對 Biopython 程式碼感興趣的人有所幫助。
此版本為非官方草案，可能會有所變更。
如果您只是想從我們的儲存庫中獲取最新的（尚未正式發布的）Biopython，請參閱我們的原始碼頁面。此頁面是關於實際使用 Git 來追蹤變更的。
如果您發現 Biopython 有問題，並且認為您知道如何修復它，那麼我們建議您遵循簡單的途徑，提交一個錯誤並描述您的修復方式。理想情況下，您應該上傳一個 patch 檔案，顯示最新版本的 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 上「fork」儲存庫。它們沒有太大的不同，實際上兩者都會在您的機器上產生一個目錄，其中包含儲存庫的完整副本。但是，如果您有 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
並點擊名為「Fork」的按鈕。這將創建一個官方 Biopython 儲存庫的 fork（基本上是一個副本），在 GitHub 上公開可見，但列在您的個人帳戶下。它應該在類似以下的網址下可見
https://github.com/yourusername/biopython
由於您的新 Biopython 儲存庫是公開可見的，因此最好將描述和首頁欄位更改為有意義的內容（即與從官方儲存庫複製的內容不同）。
如果您尚未執行此操作，請設定 SSH 金鑰並將其上傳到 github 以進行身份驗證。
現在，假設您的電腦上已安裝 Git，請在您的機器上本地執行以下命令。此「url」在您的儲存庫的 GitHub 頁面上提供（如果您已登入）
git clone git@github.com: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 "d.jones@example.com"
Biopython 嘗試遵循 PEP8 和 PEP257 中規定的程式碼慣例。
在開始處理程式碼之前，我們要求您安裝一些用於自動檢查的工具。這包括一個 Git 預先提交掛鉤，以便您的每個提交（請參閱下文）都會自動檢查是否違反 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 上的 fork。您不需要網路連線即可提交，因此您可以非常頻繁地進行提交。
如果您使用 Github，並且您正在使用您自己的分支的複製，您可以非常輕鬆地讓其他人可以使用您的變更。
一旦您認為您的變更穩定且應由其他人審閱，您可以將您的變更推回 GitHub 伺服器
git push origin demo-branch
如果您直接從官方 Biopython 分支複製，這將不起作用，因為只有核心開發人員才能擁有對主要儲存庫的寫入權限。
我們建議您實際上不要對您本地儲存庫（或您在 github 上的 fork）中的 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 本身，您可以從您的分支主頁發送「Pull Request」來通知主分支的維護者您的變更。一旦檔案被提交到主分支，您可能需要刪除您在 GitHub 上現在多餘的錯誤修復分支。可以通過選擇「編輯」，然後從編輯頁面的底部選擇「刪除儲存庫」來刪除分支。
如果您開始工作後發生了其他事情，當應用到官方儲存庫的 master 分支時，可能需要合併。在這種情況下，我們可能會要求您通過 rebase 您的工作來提供幫助。
git fetch upstream
git checkout demo-branch
git rebase upstream/master
希望您的分支和官方儲存庫的 master 分支之間的唯一變更是微不足道的，git 會自動處理一切。如果不是，您將必須手動處理衝突。如果這樣做有效，您可以通過替換現有的（pre-rebase）分支來更新 Pull Request。
git push origin demo-branch --force
但是，如果 rebase 沒有順利進行，請使用以下命令放棄（希望 Biopython 開發人員可以為您解決 rebase 或合併的問題）
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 佇列從其他人的 fork 分支中挑選提交。有關詳細資訊，請參閱此 GitHub 部落格文章。雖然預設會將變更應用到您目前的分支，但您通常會使用新的整合分支來執行此操作，然後將其提取到您的本地計算機以測試所有內容，然後再將其合併到您的主分支。
本節旨在給予 Biopython 開發人員，他們被允許將變更提交到 Biopython 主要「官方」分支。它描述了典型的活動，例如合併來自 git 分支和修補程式的貢獻程式碼變更。
目前，Biopython 的主要分支託管在 github 上。為了對主分支進行變更，您需要一個 GitHub 帳戶，並且您需要被新增為 Biopython 帳戶的協作者。這只需要執行一次。如果您有 GitHub 帳戶，但您還不是協作者，並且您認為您應該是（例如，您在 open-bio 伺服器上有 cvs 帳戶）：請 Peter 新增您（這適用於常規貢獻者，因此如果您只有一個變更要做，請考慮通過其中一位開發人員提交您的變更）。
一旦您成為協作者，您就可以使用私有 url 提取 Biopython 官方分支。如果您想要建立一個新的儲存庫（連結到主分支），您只需複製它
git clone git@github.com:biopython/biopython.git
它會建立一個名為「biopython」的新目錄，其中包含官方分支的本機副本。它還將「origin」設定為 GitHub 副本。這是建議的方式（至少對於初學者而言），因為它可以將意外將變更推送到官方 GitHub 分支的風險降到最低。
或者，如果您已經有一個工作的 git 儲存庫（包含您的分支和您自己的變更），您可以使用 git 的「remote command」新增一個連結到官方分支… 但我們在這裡不會介紹。
在以下章節中，我們假設您已遵循建議的方案，並且您的 .git/config 檔案中有以下條目
[remote "origin"]
url = git@github.com: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 的好指南