棄用政策

由於生物資訊學和計算生物學發展迅速，一些先前開發的 Biopython 模組在當今世界可能不再相關。為了保持程式碼庫的整潔，我們的目標是棄用並從 Biopython 中移除此類程式碼，同時避免對可能依賴舊程式碼的使用者造成任何不愉快的意外。

我們使用相同的流程來棄用過時的模組、方法、函式和類別。

我們在 Biopython 原始碼中保留一個純文字檔案來記錄這些變更，命名為 DEPRECATED.rst。

這是目前從 Biopython 棄用和移除程式碼的政策

• 首先，在 Biopython 郵件列表上詢問給定的程式碼是否有任何使用者。請記住，並非所有使用者都關注 biopython 郵件列表。
• 考慮在棄用之前將模組宣告為「過時」。沒有程式碼變更，只是
  • 在 DEPRECATED 檔案中記錄這一點，
  • 在模組說明字串的第一行新增「(OBSOLETE)」，
  • 使用模組說明字串解釋為什麼模組已過時，以及應該使用什麼來替代。
  • 由於在 Biopython 程式碼庫中應避免使用過時的程式碼，因此開始使用新推薦的程式碼來取代過時的程式碼。這也有助於驗證程式碼是否真的可以棄用和移除。為了更輕鬆地追蹤變更，可以使用多個提取請求來取代過時的程式碼。
  • 開始重新組織或重寫 Biopython 文件，引導使用者使用新推薦的程式碼，並遠離已棄用的程式碼。然而，在棄用過程中，過時程式碼的描述應保留在文件中，直到實際移除程式碼為止。
• 如果沒有明顯的使用者，那麼實際上將其棄用
  • 在 DEPRECATED 檔案中記錄這一點，
  • 在模組說明字串的第一行新增「(DEPRECATED)」，
  • 使用模組說明字串解釋所需的任何遷移，最好附上範例或教程參考。
  • 最重要的是，向程式碼新增 BiopythonDeprecationWarning（Python 的 DeprecationWarning 預設是靜音的）

import warnings
from Bio import BiopythonDeprecationWarning

warnings.warn(
    "Bio.SomeModule has been deprecated, and we intend to remove it"
    " in a future release of Biopython. Please use the SomeOtherModule"
    " instead, as described in the Tutorial. If you would like to"
    " continue using Bio.SomeModule, please contact the Biopython"
    " developers via the mailing list or GitHub.",
    BiopythonDeprecationWarning,
)

• 在測試中關閉新的警告，例如，如果您的測試使用 from Bio import SomeModule，請將其替換為

from Bio import BiopythonDeprecationWarning

with warnings.catch_warnings():
    warnings.simplefilter("ignore", BiopythonDeprecationWarning)
    from Bio import SomeModule

• 原則上，我們要求在實際移除程式碼之前，發布兩個帶有棄用警告的 Biopython 版本。
• 此外，在發布第一個帶有棄用警告的 Biopython 版本與第一個實際移除程式碼的 Biopython 版本之間，至少應經過一年。

請參閱此處的郵件列表討論

http://lists.open-bio.org/pipermail/biopython-dev/2008-November/004920.html