NEP 0 — 目的與流程#

作者:: Jarrod Millman <millman@berkeley.edu>
狀態:: 活躍
類型:: 流程
建立:: 2017-12-11

什麼是 NEP？#

NEP 代表 NumPy 增強提案。NEP 是一份設計文件，旨在向 NumPy 社群提供資訊，或描述 NumPy 或其流程或環境的新功能。NEP 應提供該功能的簡潔技術規範以及該功能的理由。

我們希望 NEP 成為提議主要新功能、收集社群對問題的意見，以及記錄已納入 NumPy 的設計決策的主要機制。NEP 作者負責在社群內建立共識並記錄不同意見。

由於 NEP 以版本控制儲存庫中的文字檔案形式維護，因此其修訂歷史記錄是功能提案的歷史記錄 [1]。

類型#

NEP 有三種類型

標準追蹤 NEP 描述 NumPy 的新功能或實作。
資訊型 NEP 描述 NumPy 設計問題，或向 Python 社群提供一般指南或資訊，但不提出新功能。資訊型 NEP 不一定代表 NumPy 社群共識或建議，因此使用者和實作者可以自由忽略資訊型 NEP 或遵循其建議。
流程 NEP 描述圍繞 NumPy 的流程，或提出對流程的變更（或流程中的事件）。流程 NEP 類似於標準追蹤 NEP，但適用於 NumPy 語言本身以外的領域。它們可能會提出實作，但不會針對 NumPy 的程式碼庫；它們需要社群共識。範例包括程序、指南、決策流程的變更，以及 NumPy 開發中使用的工具或環境的變更。任何元 NEP 也被視為流程 NEP。

NEP 工作流程#

NEP 流程始於 NumPy 的新想法。強烈建議單一 NEP 包含單一主要提案或新想法。小型的增強功能或修補程式通常不需要 NEP，並且可以透過向 NumPy repo 發送提取請求來注入到 NumPy 開發工作流程中。repo。NEP 越集中，就越容易成功。如果有疑問，請將您的 NEP 分割成幾個重點明確的 NEP。

每個 NEP 都必須有一位倡導者，即使用以下描述的風格和格式撰寫 NEP、在適當的論壇中引導討論，並嘗試圍繞該想法建立社群共識的人。NEP 倡導者（又名作者）應首先嘗試確定該想法是否適合 NEP。發布到 numpy-discussion 郵件列表是執行此操作的最佳方式。

提案應透過 GitHub 提取請求作為草稿 NEP 提交至 doc/neps 目錄，名稱為 nep-<n>.rst，其中 <n> 是適當指定的四位數數字（例如，nep-0000.rst）。草稿必須使用 NEP X — 範本與說明檔案。

一旦 NEP 的 PR 就位，就應該向郵件列表發布包含直到「向後相容性」部分的文章，目的是將那裡的討論限制在使用和影響上。關於提取請求的討論將具有更廣泛的範圍，還包括實作的詳細資訊。

在最早的便利時間，應合併 PR（無論是否在討論期間被接受）。作者可以進行其他 PR 以更新或擴展 NEP，或者維護者可以設定其狀態、討論 URL 等。

標準追蹤 NEP 由兩部分組成：設計文件和參考實作。通常建議至少與 NEP 共同開發原型實作，因為原則上聽起來不錯的想法，有時在經過實作測試後會變得不切實際。通常，將原型實作作為 PR 提供給 NumPy repo 是有意義的（確保適當地將 PR 標記為 WIP）。

審查與決議#

NEP 在郵件列表中討論。NEP 狀態的可能路徑如下

所有 NEP 都應以「草稿」狀態建立。

最終，經過討論後，可能會達成共識，即應接受 NEP – 詳細資訊請參閱下一節。此時狀態變為「已接受」。

一旦 NEP 被「已接受」，就必須完成參考實作。當參考實作完成並納入主要原始碼儲存庫後，狀態將變更為「最終」。

為了在承諾語言功能或標準函式庫 API 的長期穩定性之前，允許收集額外的設計和介面回饋，NEP 也可能被標記為「暫定」。這是「暫時接受」的縮寫，表示該提案已被接受納入參考實作，但在完整設計被視為「最終」之前，仍需要額外的使用者回饋。與常規已接受的 NEP 不同，即使相關變更已包含在 Python 版本中，暫時接受的 NEP 仍可能被「拒絕」或「撤回」。

在可能的情況下，最好縮小提案範圍，以避免需要依賴「暫定」狀態（例如，將某些功能延後到稍後的 NEP），因為此狀態可能會導致更廣泛的 NumPy 生態系統中出現版本相容性挑戰。

NEP 也可以被指定為「延遲」狀態。當 NEP 沒有進展時，NEP 作者或核心開發人員可以將 NEP 指定為此狀態。

NEP 也可能被「拒絕」。也許在一切都說完做完之後，這並不是一個好主意。記錄這一事實仍然很重要。「撤回」狀態類似，表示 NEP 作者自己已決定 NEP 實際上是一個壞主意，或者已接受競爭提案是更好的替代方案。

當 NEP 被「已接受」、「拒絕」或「撤回」時，應相應地更新 NEP。除了更新狀態欄位外，至少應新增「決議」標頭，並連結到郵件列表存檔中的相關主題。

NEP 也可能被不同的 NEP「取代」，導致原始 NEP 過時。應分別新增包含對原始 NEP 和新 NEP 參考的「Replaced-By」和「Replaces」標頭，例如 :ref:`NEP#number`。

流程 NEP 也可能具有「活躍」狀態，如果它們永遠不打算完成，例如 NEP 0（此 NEP）。

NEP 如何被接受#

NEP 透過所有感興趣的貢獻者的共識而被「接受」。我們需要一種具體的方法來判斷是否已達成共識。當您認為 NEP 已準備好接受時，請發送電子郵件至 numpy-discussion 郵件列表，主旨類似於

接受 NEP #<number>: <title> 的提案

在您的電子郵件正文中，您應該

連結到 NEP 的最新版本，
簡要描述任何主要爭議點以及它們是如何解決的，
包含類似這樣的句子：「如果自此電子郵件發出後 7 天內沒有實質性異議，則 NEP 將被接受；有關更多詳細資訊，請參閱 NEP 0。」

例如，請參閱：https://mail.python.org/pipermail/numpy-discussion/2018-June/078345.html

發送電子郵件後，您應確保從 NEP 的「討論」部分連結到電子郵件串，以便人們稍後可以找到它。

通常，NEP 作者將是發送此電子郵件的人，但任何人都可以這樣做 – 重要的事情是確保每個人都知道 NEP 何時處於即將被接受的邊緣，並給予他們最後一次回應的機會。如果有任何特殊原因要將最終評論期延長超過 7 天，那也沒關係，只需在電子郵件中說明即可。您不應少於 7 天，因為有時人們會出差或類似情況，需要一些時間來回應。

總體而言，目標是確保社群達成共識，而不是提供僵化的政策讓人們試圖鑽漏洞。如果有疑問，請傾向於要求更多回饋並尋找妥協的機會。

如果最終評論期過去後沒有任何實質性異議，則 NEP 可以正式標記為「已接受」。您應發送後續電子郵件通知列表（慶祝表情符號是可選的，但鼓勵使用 🎉✨），然後透過將其 :Status: 設定為「已接受」，並將其 :Resolution: 標頭設定為指向您的後續電子郵件的連結來更新 NEP。

如果存在實質性異議，則 NEP 仍保持「草稿」狀態，討論照常繼續，並且一旦異議解決，可以稍後再次提出接受提案。

在不尋常的情況下，可能會要求 NumPy 指導委員會決定有爭議的 NEP 是否被「接受」。

維護#

一般而言，標準追蹤 NEP 在達到「最終」狀態後將不再修改，因為程式碼和專案文件被視為已實作功能的最終參考。但是，最終確定的標準追蹤 NEP 可以根據需要進行更新。

流程 NEP 可能會隨著時間的推移而更新，以反映開發實務和其他詳細資訊的變更。在這些情況下遵循的精確流程將取決於正在更新的 NEP 的性質和目的。

格式與範本#

NEP 是使用 reStructuredText 格式的 UTF-8 編碼文字檔案。有關更多資訊，請參閱 NEP X — 範本與說明檔案和 reStructuredTextPrimer。我們使用 Sphinx 將 NEP 轉換為 HTML，以便在網路上檢視 [2]。

標頭前言#

每個 NEP 都必須以標頭前言開始。標頭必須按以下順序出現。標記為 * 的標頭是可選的。所有其他標頭都是必需的。

  :Author: <list of authors' real names and optionally, email addresses>
  :Status: <Draft | Active | Accepted | Deferred | Rejected |
           Withdrawn | Final | Superseded>
  :Type: <Standards Track | Process>
  :Created: <date created on, in dd-mmm-yyyy format>
* :Requires: <nep numbers>
* :NumPy-Version: <version number>
* :Replaces: <nep number>
* :Replaced-By: <nep number>
* :Resolution: <url>

「作者」標頭列出所有 NEP 作者的姓名，以及可選的電子郵件地址。「作者」標頭值的格式必須是

Random J. User <[email protected]>

如果包含電子郵件地址，則為

Random J. User

如果未提供地址，則為。如果有多位作者，則每位作者應佔據單獨一行。