提交提案

在提交新的提案之前，请考虑以下事项

许多个人和公司（大大小小）都在生产项目中愉快地使用 Sails（包括新建项目和成熟项目），并且使用的是当前发布的功能集。造成这种情况的一个重要原因是，Sails 的构建过程中，核心团队也在运营一个开发工作室，Sails 被用于将许多不同类型的应用程序从概念到生产，然后作为这些应用程序在未来几年维护的后端。

就像 Ruby on Rails 的典型案例一样，这意味着 Sails 从一开始就被设计成既对开发者友好又对企业友好，使用约定优于配置的方法。**约定**使构建新的 Sails 应用程序和在不同的现有 Sails 应用程序之间切换变得快速而简单，而**可配置性**允许 Sails 开发人员灵活地自定义这些应用程序，并在它们成熟时使用底层工具链的全部功能（配置、插件/覆盖、Express、Socket.io、Node.js 和 JavaScript）。

在 Sails 的第一个生命周期中，**可配置性**的要求变得更加重要。随着用户群的增长，Sails 开始被用于各种不同的项目，并且被各种不同偏好的开发人员使用，功能请求的数量激增。Sails 在 2013 年通过重写其核心并使其天生具有互操作性来解决这个问题。

• 由于 Sails 应用程序只是 Node 应用程序，因此您可以利用 数百万 个 NPM 包中的任何一个，这些包位于 https://npmjs.net.cn。（最近，您还可以利用从 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.node.org.cn/plugins 上提供的数千个 Grunt 插件中的任何一个。
• Sails 的钩子系统允许您禁用、替换或自定义应用程序中的大量功能，包括 Sails 核心部分，例如用 Gulp 替换 Grunt。
• Waterline 的适配器接口允许您将模型插入任何数据库，例如 Oracle、MSSQL 或 Orient DB。
• Skipper 的适配器接口允许您将传入的流式文件上传插入任何 Blob 存储容器，例如 S3、GridFS 或 Azure。
• Sails 的生成器系统允许您完全控制当您运行 sails new 或 sails generate * 时，Sails 命令行工具生成的全部文件和文件夹。

重要的是要认识到，今天，Sails 中的大多数（但肯定不是全部）新功能都可以使用一个或多个现有的插件接口来实现，而不是对核心进行更改。如果您请求的功能是该规则的例外，那么请继续——但请意识到，您提案中最重要的部分可能是清楚地解释为什么您建议的功能今天无法实现。

Sails 的核心维护人员会审查所有功能提案，我们会尽最大努力参与这些 PR 中的讨论。但是，许多这些提案有时会涉及来回讨论，这可能需要它们开放数月时间。因此，在开始时了解这一点很重要，如果您正在提出一个功能，那么您有责任充分说明该功能的工作原理；即如何使用它，如何配置它，特别是它的实现——也就是说，需要更改哪些模块才能使其成为现实，如何对其进行测试，它是否会是重大或次要版本破坏性更改，以及对 Sails 官方文档所需的添加和/或修改。

考虑到这一点，要提交新功能或现有功能扩展的提案，请执行以下步骤

0. 首先，查看 ROADMAP.MD 中的 backlog 表，并搜索该文件中的打开的拉取请求，以确保您的更改尚未被提出。
   • 如果 PR（拉取请求）已合并，则表示核心维护人员已 (A) 查看了拉取请求中的提案和讨论，(B) 个人同意该功能非常适合 Sails 核心，并且 (C) 已与 @mikermcneil 确认了该决定。这也意味着该提案现在位于 ROADMAP.md 中的积压工作中，这意味着核心团队将愿意合并一个包含代码更改的拉取请求，以将该功能添加到 Sails 核心（假设该拉取请求遵循我们的编码风格约定和本节中的指南）。
   • 如果 PR 已关闭但未合并，则表示核心团队已决定该功能请求不应成为 Sails 核心的部分。仅仅因为提案已关闭并不意味着该功能永远无法在 Sails 中实现，它仅仅意味着 (A) 需要对其规范进行不同的说明才能合并，或者 (B) 需要将其作为插件实现（即钩子、适配器、生成器、视图引擎、grunt/gulp 任务等）。
   • 如果 PR 处于打开状态，则表示 (A) 它最近发布，(B) 仍在进行积极的讨论，(C) 核心维护人员尚未有时间查看它，或者最常见的情况是 (D) 一位或多位核心维护人员已查看并可能已回复了该提案，但团队认为没有足够的信息做出明确的“是”或“否”判断。这种情况非常普遍，因为有时需要花费大量时间来制定足够详尽的规范才能合并到积压工作中。核心维护人员会根据时间允许的情况审查和参与提案，但最终，开发者请求功能需要承担充分说明功能的工作。
   • 虽然 Sails 的一些核心维护人员会仔细筛选来自 GitHub 的电子邮件（因为他们有时也希望收到其他电子邮件），但许多贡献者每次发布新评论时都会收到 GitHub 通知。出于对他们的尊重，请勿 *bump* 或 :+1: 功能提案。相反，请用简洁的 (3-5 句话) 说明您对该功能的实际使用案例。
1. 如果尚不存在，请创建一个拉取请求以编辑 ROADMAP.MD（最简单的方法是在登录 GitHub 的情况下打开 ROADMAP.md 并单击“编辑”按钮）。
2. 在 **Backlog** 表中添加一行，其中包含对该功能的非常简短的描述，然后将更改作为拉取请求提交（最简单的方法是使用上面讨论的 GitHub UI，进行更改，然后按照屏幕上的说明进行操作）。
3. 在拉取请求的描述中
   • 首先，以简洁的描述 (3-5 句话) 写出您正在提出的功能的高级摘要，重点关注一个令人信服的实际使用案例，在该案例中，您为工作、客户、公司、非营利工作或独立爱好项目构建或维护的 Sails 应用程序可以通过此功能或更改变得更容易。
   • 接下来，使用相关的代码文件链接以清晰的散文描述为什么在不更改 Sails 核心（即使用一个或多个现有的插件机制）的情况下实现该功能会很困难或不可能。如果不是这种情况，并且此功能可以作为插件实现，那么请重新考虑编写您的提案（核心团队不太可能接受它）。如果您是一名或多名插件的作者，并且认为您或其他用户会受益于将您的工作包含在 Sails 核心，请直接联系核心团队（请参阅上面提交“关于该项目的高级问题或疑虑”的说明）。
   • 最后，如果您有时间，请尝试为该功能提出规范（其配置、用法以及如何实现）。如果您没有时间写出详尽规范的第一稿，请在您的功能请求中说明这一点，并澄清这将取决于具有相同或类似使用案例的其他贡献者来完成此提案。

不符合这些指南的提案将被关闭，并附有回复，要求提交者审查本贡献指南。如果这种情况发生在您身上，请意识到这与个人无关，并且甚至可能再次发生。请考虑，Sails 中现有的插件系统投入了大量精力，因此对核心的任何提议更改都必须仔细考虑其对现有插件、现有应用程序和框架未来开发的影响。许多 Sails 贡献者已经非常熟悉 Sails 中各种系统之间的交互方式，并且乐于为您提供帮助；但为了使此过程高效，所有新功能和增强功能都必须遵循一组通用的基本规则。

如果您的功能提案被合并……

你的提案被合并并不一定意味着你负责实现该功能；当然，你也不必负责维护未来可能影响该功能的所有更改。这项特权保留给 Mike 和核心团队的其他成员；这就是为什么从第一天起，详细说明你提议的功能的使用、配置和实现愿景如此重要的原因。制定这种详细的提案并非易事，通常比实际实现需要花费更多精力。但如果提案被接受，它就成为项目使命的一部分：这意味着一旦它被实现并合并，核心团队将致力于将其作为 Sails 的一部分进行维护。