NEP 0 — 目的與流程#
- 作者:
Jarrod Millman <millman@berkeley.edu>
- 狀態:
活動中
- 類型:
流程
- 建立日期:
2017-12-11
什麼是 NEP？#
NEP 代表 NumPy 增強提案 (NumPy Enhancement Proposal)。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 提交提取請求 (pull request) 來注入 NumPy 開發工作流程中。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 過時。Replaced-By 和 Replaces 標頭應分別包含對原始和新 NEP 的參考，例如 :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: 設定為 Accepted，並將其 :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
如果未提供地址。如果有多位作者，則每位作者應佔一行。
討論#
參考文獻與腳註#
著作權#
本文件已置於公共領域。