提交提案

在提交新提案之前，請考慮以下事項

許多個人和公司（無論規模大小）都非常樂意在生產專案（包括全新專案和成熟專案）中使用目前已發布且功能齊全的 Sails。其中一個主要原因是 Sails 在核心團隊經營開發工作室時就已建立，當時它被用來將許多不同類型的應用程式從概念轉變為生產，然後在接下來的幾年中作為這些應用程式維護的後端。

就像 Ruby on Rails 的典型案例一樣，這表示 Sails 從一開始就被設計為對開發人員和企業都友善，並採用慣例優於設定的方法。慣例讓建立新的 Sails 應用程式以及在不同的現有 Sails 應用程式之間切換變得快速而容易，而可配置性則讓 Sails 開發人員能夠靈活地自訂這些成熟的應用程式，並充分利用底層工具鏈的強大功能（配置、外掛程式/覆蓋、Express、Socket.io、Node.js 和 JavaScript）。

在 Sails 上線的第一年，可配置性的要求變得更加重要。隨著使用者群的增長，Sails 開始被應用於各種不同的專案，並且被具有各種不同偏好的開發人員使用，功能請求也隨之激增。Sails 在 2013 年透過重寫其核心並使其具有內在的互操作性來解決這個問題

• 由於 Sails 應用程式只是 Node 應用程式，您可以利用 數百萬個 NPM 套件，網址為 http://npmjs.org。（最近，您還可以利用數百個自動記錄的機器函式，這些函式來自 NPM，網址為 http://node-machine.org）
• 由於 Sails 使用與 Express 和 Connect 相同的 req/res/next 模式，您可以在您的應用程式中利用為這些中介軟體框架編寫的任何中介軟體，例如 Lusca（來自 Paypal 的安全中介軟體）或 morgan（HTTP 記錄工具）。
• 由於 Sails 使用 Consolidate，您可以使用任何與 Express 相容的視圖引擎，例如 Jade、Dust 或 Handlebars。
• 由於 Sails 使用熟悉的 MVC 專案結構，您和/或您團隊中的其他開發人員可以快速上手了解應用程式的運作方式、資料庫架構，甚至大致了解常見配置選項的位置。
• 由於 Sails 使用 Grunt，您可以在您的應用程式中安裝和使用 https://grunt.dev.org.tw/plugins 上提供的數千個 Grunt 外掛程式。
• Sails 的 Hook 系統允許您停用、替換或自訂應用程式中的大量功能，包括 Sails 核心的部分，例如將 Grunt 替換為 Gulp。
• Waterline 的 Adapter 介面允許您將模型插入任何資料庫，例如 Oracle、MSSQL 或 Orient DB。
• Skipper 的 Adapter 介面允許您將傳入的串流檔案上傳插入任何 Blob 儲存容器，例如 S3、GridFS 或 Azure。
• Sails 的產生器系統允許您完全控制當您執行 sails new 或 sails generate * 時，Sails 命令列工具產生的所有檔案和資料夾。

重要的是要意識到，如今，Sails 中的大多數（但當然不是全部）新功能都可以使用一個或多個現有的外掛程式介面來實現，而不是變更核心。如果您請求的功能是該規則的例外，那麼請繼續進行——但請意識到，也許您的提案最重要的部分是清楚地解釋為什麼您建議的內容在今天是不可能的。

Sails 的核心維護人員會審查所有功能提案，我們會盡力參與這些 PR 中的討論。但是，許多這些提案有時可能涉及來回討論，可能需要開放數個月。因此，重要的是要事先了解，如果您要提出功能，您有責任充分說明該功能將如何運作；即它將如何使用、如何配置，尤其是它的實作——也就是說，哪些模組需要更改才能實現它，它將如何測試，它是否會是主要或次要版本的破壞性變更，以及官方 Sails 文件中需要新增和/或修改的內容。

考慮到這一點，若要提交新功能或現有功能的擴充提案，請採取以下步驟

0. 首先，查看 ROADMAP.MD 中的 backlog 表格，並搜尋該檔案中的開放 Pull Request，以確保您的變更尚未被提出。
   • 如果 PR（Pull Request）已合併，則表示核心維護人員已 (A) 審閱了 Pull Request 中的提案和討論，(B) 親自同意該功能非常適合 Sails 核心，以及 (C) 與 @mikermcneil 確認了該決定。這也表示該提案現在位於 ROADMAP.md 的 Backlog 中，這表示核心團隊願意合併包含程式碼變更的 Pull Request，將該功能新增至 Sails 核心（假設該 Pull Request 遵循我們的程式碼風格慣例和本節中的指南）。
   • 如果 PR 已關閉但未合併，則表示核心團隊已決定該功能請求不應成為 Sails 核心的一部分。僅僅因為提案已關閉並不表示該功能永遠無法在 Sails 中實現，這僅表示 (A) 它需要以不同的方式規格化才能合併，或 (B) 它需要作為外掛程式（即 Hook、Adapter、產生器、視圖引擎、Grunt/Gulp 任務等）實作。
   • 如果 PR 開啟，則表示 (A) 最近發布，(B) 仍有活躍的討論正在進行中，(C) 核心維護人員尚未有時間查看，或最常見的情況是 (D) 一個或多個核心維護人員已查看，甚至可能已回覆提案，但團隊認為沒有足夠的資訊來做出堅定的「是」或「否」判斷。第四種情況非常常見，因為有時需要花費大量時間來制定一個足夠詳盡的規格以合併到 Backlog 中。核心維護人員會在時間允許的情況下盡可能多地審查和貢獻提案，但最終，開發人員有責任完成充分規格化功能的工作。
   • 雖然一些 Sails 的核心維護人員會仔細篩選來自 GitHub 的電子郵件（因為他們也希望收到其他電子郵件），但許多貢獻者每次發布新評論時都會收到 GitHub 通知。出於對他們的尊重，請勿 *bump* 或 :+1: 功能提案。相反，請簡潔地（3-5 句話）解釋您在現實世界中使用該功能的案例。
1. 如果尚不存在，請建立一個 Pull Request 來編輯 ROADMAP.MD（最簡單的方法是在登入 GitHub 時開啟 ROADMAP.md，然後按一下「編輯」按鈕）。
2. 在 Backlog 表格中新增一行，簡要描述該功能，然後將變更作為 Pull Request 提交（最簡單的方法是使用如上所述的 GitHub UI，進行變更，然後按照螢幕上的指示操作）。
3. 在您的 Pull Request 的描述中
   • 首先，寫下您提出的功能的高階摘要，作為一個簡潔的描述（3-5 句話），重點圍繞一個令人信服的真實世界使用案例，在該案例中，您為您的工作、您的客戶、您的公司、您的非營利工作或您的獨立業餘專案建立或維護的 Sails 應用程式將因這項功能或變更而變得更容易。
   • 接下來，以清晰的文字並附上程式碼檔案的相關連結，準確描述為什麼如果不變更 Sails 核心（即使用一個或多個現有的外掛程式機制），就很難或不可能實作該功能。如果情況並非如此，並且此功能可以作為外掛程式實作，那麼請重新考慮撰寫您的提案（核心團隊不太可能接受它）。如果您是一個或多個外掛程式的作者，並且認為您或其他使用者將受益於將您的工作納入 Sails 核心，請直接聯絡核心團隊（請參閱上面提交「關於專案的高階問題或疑慮」的說明）。
   • 最後，如果您有時間，請初步嘗試提出此功能的規格（其配置、用法以及其實作方式）。如果您沒有時間寫出完整規格的初稿，請在您的功能請求中說明這一點，並澄清這將取決於其他具有相同或相似使用案例的貢獻者來完成此提案。

不符合這些指南的提案將被關閉，並附上要求提交者審閱本貢獻指南的回覆。如果這種情況發生在您身上，請意識到這絕非針對個人，甚至可能再次發生。請考慮到 Sails 中現有的外掛程式系統已投入了大量精力，因此任何對核心的擬議變更都必須仔細考慮其對現有外掛程式、現有應用程式以及框架未來開發的影響。許多 Sails 貢獻者已經非常熟悉 Sails 中各種系統如何互動，並且願意為您提供幫助；但為了使該過程有效率，重要的是所有新功能和增強功能都遵循一套通用的基本規則。

如果您的功能提案被合併...

您的提案被合併不一定表示您有責任實作該功能；您當然也不會負責維護未來可能影響所有人的該功能的變更。該特權是 Mike 和其他核心團隊成員的專屬；這就是為什麼從第一天起就詳細說明您提出的功能的使用方式、配置和實作的願景如此重要。制定這種詳細的提案並非易事，而且通常比實際實作更費力。但是，如果提案被接受，它就會成為專案使命的一部分：這表示一旦它被實作和合併，核心團隊就承諾將其作為 Sails 的一部分進行維護。