貢獻 Biopython。

Biopython 貢獻指南

所以你想貢獻 Biopython，是嗎？太棒了！新的貢獻是專案的命脈。但是，如果做得不正確，它們可能會迅速消耗寶貴的開發者時間。（我們也有正職工作！）這是一個簡短的指南，說明推薦的貢獻程式碼給 Biopython 的方式。

另請參閱教學（PDF）中關於貢獻的章節。

如果您已經到可以提出包含變更的拉取請求的程度，您應該閱讀 CONTRIBUTING.rst，其中描述了如何進行包括樣式檢查在內的自動測試。

非程式碼貢獻

即使您覺得還沒準備好或無法貢獻程式碼，您仍然可以提供協助。總是有一些可以在文件上改進的地方（甚至只是校對，或者告訴我們某個章節不夠清楚）。我們也需要郵件列表上的人員協助回答初學者問題，或參與有關新功能的辯論。也許您可以為wiki 食譜提出一般範例？

尋找專案

最好的貢獻是您在日常研究中已經使用的程式碼。這應該是您認為可能對其他人有用並且已經沒有錯誤的程式碼。如果您正在考慮送出這些程式碼，請繼續執行步驟 2：提交程式碼！

否則，仍然有很多方法可以貢獻 Biopython，無論是否涉及程式碼。您可以協助的一些事項包括：

• 更多單元測試：我們的一些模組仍然只有部分單元測試涵蓋範圍。
• 支援更多程式：正在開發許多不同的生物資訊程式。找出一個目前在 Biopython 中沒有支援的程式，並為其添加支援。
• 支援更多檔案格式：我們可以讀寫許多不同的檔案格式，但總是會有更多。對於序列和比對，請先查看 SeqIO 和 AlignIO 頁面。請注意，不鼓勵針對特定網站的 HTML 解析器，因為這些解析器需要長期維護。
• 支援資料庫：找出一個目前在 Biopython 中沒有支援的生物資料庫，並為其添加支援。
• 新增資料類型：您可以新增使用新類型資料的程式碼。這是一個困難的領域。建立一個新的、穩健且有用的資料類型很困難，除非它已經過嘗試和測試，否則我們可能會猶豫是否要新增它。
• 新增新演算法：您可以新增一個可能對其他生物學家有用的新的知名演算法。
• 解析器驗證：隨著 Biopython 支援越來越多的資料庫，維護格式解析器的難度會增加。這些格式變化非常快。因此，我們需要定期驗證解析器是否仍在運作。例如，需要檢查 GenBank 解析器，以確保它可以處理 GenBank 的每個新轉儲。
• 回歸測試：Biopython 使用回歸測試框架來確保程式碼正常運作。儘管 Biopython 中的大多數功能都經過測試，但仍然存在一些漏洞。
• 文件：教學不完整，可以使用一些工作。當您學習新套件時，新使用者可能特別有幫助。我們的 API 文件也可以進行一些修改，請參閱下面的程式碼慣例。
• 新聞發布：如果您關注郵件列表（數量相當少），我們需要有人協助總結重要文章和事件作為新聞項目。

提交程式碼

一般來說，我們會考慮任何適用於生物或化學資料的程式碼。請不要提交功能與 Biopython 中已有的程式碼大部分重疊的程式碼，除非有明顯的改進，並且您有整合程式碼的計畫。

在提交之前，請檢查

• 它是否已通用化，並且可能對其他事情有用。
• 相依性是否合理。新增對第三方命令列工具的支援是沒問題的，但是需要討論是否需要額外的 Python 函式庫。在 Biopython 中可能不會接受對商業封閉原始碼軟體的相依性。
• 程式碼將使用 Biopython 授權條款進行授權。
• 您必須擁有合法權利貢獻它並在 Biopython 授權條款下授權。
• 您是否熱衷於維護它並回覆錯誤報告。
• 您是否在程式碼中包含 docstring，並且願意撰寫文件。
• 您是否為新程式碼編寫了單元測試，或者願意編寫單元測試。

如果所有這些條款看起來都可以接受，請將您的程式碼描述發送到 biopython@biopython.org（請參閱郵件列表）。請務必在發送訊息之前訂閱 biopython 郵件列表，否則您的訊息將被郵件伺服器丟棄（這是為了避免在郵件列表上發送垃圾郵件）。請勿將程式碼直接發送到 biopython 郵件列表。相反，請透過建立問題並附加檔案或連結到您的 GitHub 分支，來使用我們的 GitHub 頁面。

程式碼慣例

Biopython 嘗試遵循 PEP 8 和 PEP 257 中規定的程式碼慣例。重要的重點是

• 類別應使用 AllFirstLetterUppercase 樣式。
• 函式應使用 lowercase_separated_by_underscores 樣式。
• 變數採用 lowercase_separated_by_underscores 或 lowercasemungedtogether 樣式，具體取決於您的喜好和變數的長度。
• _single_leading_underscores 指示不應由使用者直接呼叫的內部函式或類別。
• Tab 鍵是不好的。Python 社群中的大多數人現在都不喜歡 tab 鍵，而是更喜歡使用 4 個空格進行縮排。大多數編輯器都可以協助您處理這個問題（例如，Emacs python-mode 使用 4 個空格規則）。Python 發行版中的 Tools/scripts/reindent.py 將有助於去除檔案中的 tab 鍵。

一個值得注意的例外是模組名稱，我們傾向於使用標題大小寫。事後看來，這是不幸的，但我們受到向後相容性的限制。

正在使用 Epydoc 和/或 Sphinx apidoc 來產生原始碼的自動文件，因此在您的程式碼中加入有用的註解絕對很有用，以便它們可以反映在 API 文件中（除了記錄程式碼的所有正常原因之外）。

我們通常不會嘗試對程式碼中的註解進行任何花俏的格式化，但它們會被解釋為 reStructuredText 標記，允許使用項目符號和斜體等。這並不花俏，但它很有效，並且比嘗試處理無數種不同的方法來結構化原始碼註解更容易。

但是，有一些技巧可以讓您的文件看起來最好。主要的是

• 模組、類別和函式文件應以單行描述開始。這必須以句號結尾。

這是一個記錄模組的範例，以便 epydoc 會感到滿意

"""This is a one line description of the module followed with a period.

More information about the module and its goals and usage.
"""


class MyClass:
    """One line description of the class followed by a period.

    More information about the class -- its purpose, usage, and
    implementation.
    """

    def my_function(self, spam):
        """A terse description of my function followed with a period.

        A longer description with all kinds of additional goodies. This may
        include information about what the function does, along with
        what parameters it will be passed and what it returns. You know,
        information so people know how to use the function.
        """
        # the code ...