EEP 1：EEP 的目的與指南 #

什麼是 EEP？ #

EEP 代表 Erlang 擴展提案 (Erlang Extension Proposal) 或 Erlang 增強流程 (Erlang Enhancement Process)。這個概念借鑒自 Python 語言，以促進社群參與 Erlang 的開發。本文檔主要基於 PEP 1。EEP 是一份設計文件，向 Erlang 社群提供資訊，或描述 Erlang 或其流程或環境的新功能。EEP 應提供該功能的簡明技術規範和功能的基本原理。

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

由於 EEP 以文字檔案形式維護在版本控制的儲存庫中，因此它們的修訂歷史是功能提案的歷史記錄。

EEP 類型 #

EEP 有兩種

1. 標準追蹤 EEP 描述 Erlang 的新功能或實作。

2. 流程 EEP 描述與 Erlang 相關的流程，或提議變更（或流程中的事件）。流程 EEP 類似於標準追蹤 EEP，但適用於 Erlang 語言本身以外的領域。它們可以提出實作，但不適用於 Erlang 的程式碼庫；它們通常需要社群共識；它們不只是建議，使用者通常不能忽略它們。範例包括發佈排程、程序、指南、決策流程的變更，以及 Erlang 開發中使用的工具或環境的變更。

EEP 工作流程 #

EEP 編輯器會指派 EEP 編號並變更其狀態。請透過開啟對 https://github.com/erlang/eep 儲存庫的 Pull Request 來建立 EEP。

EEP 流程從 Erlang 的新想法開始。強烈建議單一 EEP 包含單一重要提案或新想法。EEP 越集中，往往就越成功。如果 EEP 提案看起來過於分散或過於廣泛，EEP 編輯器保留拒絕權。如果有疑問，請將您的 EEP 分成幾個重點明確的 EEP。

每個 EEP 都必須有一位擁護者 – 也就是使用以下描述的樣式和格式撰寫 EEP、在適當的論壇上引導討論，並嘗試建立社群對此想法的共識的人。EEP 擁護者（又名作者）應首先嘗試確定此想法是否適用於 EEP。建議張貼至 ErlangForum。小幅增強或修補程式通常不需要 EEP，可以透過建立對 https://github.com/erlang/otp 的 Pull Request，將其注入到 Erlang 開發工作流程中

EEP 擁護者會撰寫 EEP 的粗略但充實的草稿，並提供建議的標題。此草稿必須採用以下描述的 EEP 樣式撰寫。EEP 擁護者可以暫時將下一個可用的 EEP 編號指派給他們的 EEP，標記為「標準追蹤」或「流程」，並給予「草案」狀態。然後，EEP 擁護者將 EEP 發送到 EEP 儲存庫 (https://github.com/erlang/eep)。EEP 編輯器不會無理拒絕 EEP。拒絕 EEP 狀態的原因包括工作重複、技術上不健全、未提供適當的動機或處理回溯相容性，或與 Erlang 理念不符。

如果預先 EEP 被拒絕，作者可以選擇將預先 EEP 發送到 ErlangForum，以幫助充實它、從廣大社群獲得回饋和共識，並改進 EEP 以便重新提交。

然後，EEP 作者負責將 EEP 發佈到社群論壇，並爭取社群對其的支持。在必要時更新，EEP 作者可以簽入新版本。

標準追蹤 EEP 由兩個部分組成：設計文件和參考實作。EEP 應在開始參考實作之前進行審查和接受，除非參考實作將有助於人們研究 EEP。標準追蹤 EEP 必須包含實作 – 採用程式碼、修補程式或相同內容的 URL 形式 – 才能被視為「最終」。

EEP 作者負責收集社群對 EEP 的回饋，然後才能提交審查。未在 ErlangForum 上討論過的 EEP 將不被接受。但是，在任何可能的情況下，應避免在公共論壇上進行長時間的開放式討論。使討論保持效率的策略包括：在 ErlangForum 中建立新主題、讓 EEP 作者在早期設計階段接受私人評論、設定 Wiki 頁面等。EEP 作者應在此處使用其判斷。

一旦作者完成 EEP，他們必須通知 EEP 編輯器該 EEP 已準備好進行審查。EEP 由來自 Erlang/OTP 和 Erlang 社群的人員組成的委員會審查，他們可以接受或拒絕 EEP，或將其發回給作者進行修訂。對於預先確定為可接受的 EEP（例如，它明顯是目前的勝利和/或其實作已經被簽入），Erlang/OTP 團隊也可以啟動 EEP 審查，首先通知 EEP 作者並給予他們修訂的機會。

委員會成員是內部 Erlang/OTP 技術委員會，外加為特定情況召集的專家。

若要接受 EEP，它必須符合某些最低標準。它必須是對提議的增強功能的清晰且完整的描述。增強功能必須代表淨改善。如果適用，提議的實作必須穩固，並且不得過度複雜化解譯器。最後，提議的增強功能必須與 Erlang 理念相容，才能被接受。

一旦接受 EEP，就必須完成參考實作。當參考實作完成並被接受後，狀態將變更為「最終」。

EEP 也可指派狀態「已延期」。當 EEP 未取得進展時，EEP 作者或編輯器可以指派 EEP 此狀態。一旦 EEP 被延期，EEP 編輯器可以將其重新指派為草案狀態。

EEP 也可以是「已拒絕」。也許在所有工作都完成後，它並不是一個好主意。記錄此事實仍然很重要。

EEP 也可以被不同的 EEP 取代，使得原始 EEP 過時。

EEP 工作流程如下

某些「流程」EEP 如果永遠不打算完成，也可能具有「作用中」狀態。例如，EEP 1（此 EEP）。

成功 EEP 中應包含哪些內容？ #

每個 EEP 都應具有以下部分

1. 前言 – 包含有關 EEP 的中繼資料的 RFC 822 樣式標頭，包括 EEP 編號、簡短的描述性標題（限制為最多 44 個字元）、名稱，以及選擇性地包含每位作者的聯絡資訊等。

2. 摘要 – 對所解決技術問題的簡短 (~200 字) 描述。

3. 著作權/公有領域 – 每個 EEP 都必須明確標記為置於公有領域（請參閱此 EEP 作為範例），或依據開放出版許可證，或創用 CC 姓名標示 3.0 許可證授權。

4. 規格 – 技術規格應描述任何新語言功能的語法和語意。規格應足夠詳細，以允許競爭的、可互通的實作。

5. 動機 – 動機對於想要變更 Erlang 語言的 EEP 至關重要。它應清楚解釋為何現有的語言規格不足以解決 EEP 所解決的問題。動機不足的 EEP 提交可能會被直接拒絕。

6. 基本原理 – 基本原理透過描述設計的動機以及為何做出特定的設計決策，來充實規格。它應描述所考慮的替代設計和相關工作，例如，其他語言如何支援此功能。

   基本原理應提供社群內共識的證據，並討論討論期間提出的重要反對意見或疑慮。

7. 回溯相容性 – 所有引入回溯不相容性的 EEP 都必須包含一個章節，描述這些不相容性及其嚴重性。EEP 必須解釋作者提議如何處理這些不相容性。未充分處理回溯相容性的 EEP 提交可能會被直接拒絕。

8. 參考實作 – 參考實作必須在任何 EEP 被給予「最終」狀態之前完成，但不必在接受 EEP 之前完成。最好先完成規格和基本原理，並就此達成共識，然後再撰寫程式碼。

   最終實作必須包含適用於 Erlang 語言參考或標準函式庫參考的測試程式碼和文件。

EEP 格式和範本 #

EEP 以 UTF-8 編碼的文字檔案形式，以 Markdown 格式撰寫。EEP 33 是一個範本，其中包含如何撰寫 EEP 的說明。

在儲存庫中，還有 Markdown Perl 程式和一些用於建立EEP 索引的 Perl 指令碼。只需在最上層目錄中執行命令 ./build.pl 即可。

EEP 標頭前言 #

每個 EEP 都必須以 RFC 822 樣式標頭前言開頭，所有標頭都縮排四個空格，以使其成為 Markdown 程式碼樣式。標頭必須依以下順序顯示。標記有「*」的標頭是選用的，如下所述。所有其他標頭都是必要的

    Author: <list of authors' real names and optionally, email addrs>
    * Discussions-To: <email address>
    Status: <Draft | Active | Accepted | Deferred | Rejected |
             Final | Replaced>
    Type: <Standards Track | Process>
    * Content-Type: <text/plain | text/x-rst>
    * Requires: <eep numbers>
    Created: <date created on, in dd-mmm-yyyy format>
    * Erlang-Version: <version number>
    Post-History: <dates of postings to erlang-questions>
    * Replaces: <eep number, ...>
    * Replaced-By: <eep number, ...>

然後是 Markdown 水平線，EEP 編號和標題作為 Markdown 標頭 2，以及空白行，所有都是必要的

****
EEP <eep number>: <eep title>
----

Author 標頭會列出所有 EEP 作者/擁有者的名稱，以及選擇性地列出電子郵件地址。Author 標頭值的格式必須為

Random J. User <address@dom.ain>

如果包含電子郵件地址，則使用此格式；如果沒有提供地址，則僅使用

Random J. User

此格式。

如果有多位作者，則每位作者都應遵循 RFC 2822 連續行慣例，單獨放在一行上。請注意，個人電子郵件地址應被遮蔽，以防止垃圾郵件收集器收集。

Type 標頭指定 EEP 的類型：標準追蹤或流程。

Created 標頭會記錄指派 EEP 編號的日期，而 Post-History 用於記錄將新版本的 EEP 發佈到 erlang-questions 的日期。兩個標頭都應採用 dd-mmm-yyyy 格式，例如 14-Aug-2009。

標準追蹤 EEP 必須具有 Erlang-Version 標頭，指出該功能將發佈或已發佈的版本 Erlang。
流程 EEP 不需要 Erlang-Version 標頭。版本必須採用與 Erlang/OTP 專案的 Git 標記架構相同的格式。

EEP 可以具有 Requires 標頭，指出此 EEP 依賴的 EEP 編號。

EEP 也可能會有一個 Replaced-By 標頭，表示該 EEP 已被後續的 EEP 取代；其值為取代目前文件的 EEP 編號。較新的 EEP 必須具有一個 Replaces 標頭，其中包含它所取代的 EEP 編號。

輔助檔案 #

EEP 可能包含輔助檔案，例如圖表。這些檔案必須命名為 eep-XXXX-Y.ext，其中 “XXXX” 是 EEP 編號，“Y” 是一個序號（從 1 開始），而“.ext” 則由實際的檔案副檔名取代（例如“.png”）。

回報 EEP 錯誤或提交 EEP 更新 #

您如何回報錯誤或提交 EEP 更新取決於幾個因素，例如 EEP 的成熟度、EEP 作者的偏好以及您的評論性質。對於 EEP 的早期草稿階段，最好直接將您的評論和變更發送給 EEP 作者。對於更成熟或已完成的 EEP，您可能需要將更正提交至 EEP 儲存庫。

如果您不確定應將變更發送到哪裡，請先與 EEP 作者和/或 EEP 編輯確認。

EEP 作者可以透過提交變更到他們的 pull requests 來更新 EEP。

轉移 EEP 所有權 #

有時有必要將 EEP 的所有權轉移給新的負責人。一般而言，我們希望保留原始作者作為轉移後 EEP 的共同作者，但這實際上取決於原始作者。轉移所有權的一個好理由是因為原始作者不再有時間或興趣更新它或完成 EEP 流程，或者已經從網路上消失（即無法聯繫或沒有回覆電子郵件）。轉移所有權的一個壞理由是因為您不同意 EEP 的方向。我們試圖就 EEP 達成共識，但如果無法達成，您可以隨時提交一個競爭的 EEP。

如果您有興趣接管 EEP 的所有權，請發送訊息要求接管，並同時發送給原始作者和 EEP 編輯。如果原始作者沒有及時回覆電子郵件，EEP 編輯將單方面做出決定（這並非表示這些決定不能被撤銷）。

版權 #

本文件置於公共領域或在 CC0-1.0-Universal 授權下，以較寬鬆者為準。