Sails 框架 Pull Request 提交全指南从 Fork 到合入的完整实战流程【免费下载链接】sailsRealtime MVC Framework for Node.js项目地址: https://gitcode.com/gh_mirrors/sa/sails本文面向希望为 SailsNode.js 实时 MVC 框架贡献代码的开发者系统讲解向 Sails 核心仓库提交 Pull RequestPR的完整操作链路包括贡献前的规范确认、Fork 与 Clone、同步上游更新、编写补丁与测试、发起 PR以及如何用npm link让本地应用直接运行你的 Sails Fork 版本。读完本文你将掌握一套可直接照做的 PR 提交流程并理解 Sails 项目为何要求每份提交都配套测试与代码规范。一、先读官方贡献指南提交 PR 前的准入门槛本指南定位为“官方贡献指南的支撑文档”重点帮助你走通 PR 提交的“操作细节”。在开始之前请先阅读仓库根目录下的 CONTRIBUTING.md当前仓库内该文件已将完整说明指向文档站点“Contributing”栏目并结合 代码提交规范 一文确认你的改动类型。Sails 核心接受的代码贡献只有两种类型提交前务必对号入座补丁Patches小而精准的修复覆盖从错别字到时序问题的各类小改动。例如删除文件顶部一个未使用的require()或者修复一个导致 Travis 上 master 分支测试挂掉的笔误。需要特别警惕即使看似无关紧要的改动只要影响了 Sails 某个已文档化特性的用法或者新增了未文档化的公开函数就不算“补丁”跨多文件改空白、改变量名的“大型重构”同样不算补丁。新特性New features必须是 ROADMAP.md 中已经汇总过的 TODO 项并在随附的 PR 中给出更详细信息。凡是不在 ROADMAP 中的内容都不应作为新特性提交。规范还划出了几条硬性红线见 代码提交规范 的 General rules核心代码只能用 JavaScript 编写支持 maintained LTS 的 JavaScript 语法不能使用 CoffeeScript、TypeScript 或其他需要预编译/转译的语言——包括核心 hooks 与核心 generators 在内。用户态代码随意用 ES6/TS/CoffeeScript 都没问题但提交给 Sails core 的 PR 必须保持一致的 JS 风格。不要顺手“自动格式化代码”或去修复核心已有文件里你认为的风格问题。每个 PR窄聚焦于单一目标改动文件数、改动行数越少越好。不要提交实现或增强特性的 PR除非基于非常明确界定的提案动手前先在 issue/讨论中告知维护者你在做这项工作并保持进度同步否则沉默可能被视作弃权他人会抢先开工。对 Express、Socket.io 等package.json中列出的外部依赖的修改应提交到对应项目仓库Sails 仓库无法受理。提示若对改动是否算“补丁”拿不准请务必在动手前先到 issue tracker 提问或联系核心团队确认——尤其当你计划做一件大事时。没有什么比辛苦写完的代码因与维护者规划不一致而被拒更令人沮丧的了。二、Fork 与 Clone建立你的个人工作副本Sails 是一个实时 MVC 框架lib/index.js 为包入口仓库代码量不小包含 lib/核心实现、test/测试套件、docs/文档等目录。因此直接在主干上开发是不现实的标准流程从 Fork 开始。第一步Fork 仓库。在 GitHub 上打开 Sails 仓库页面点击右上角的 Fork 按钮在你的账户下生成一份副本。第二步Clone 到本地。将你账户下的 Fork 克隆到本地文件系统git clone gitgithub.com:YOUR_USER_NAME/sails.git把YOUR_USER_NAME替换为你的 GitHub 用户名。克隆完成后你会得到一个包含完整源码、测试与文档的本地仓库。建议先跑一遍npm install安装依赖为后续开发与测试做准备。三、Update让 Fork 与上游主干保持同步如果你已经 fork 过一段时间上游 master 可能新增了大量提交。在动手改代码之前先把上游的最新改动合入你的本地分支# 在你的项目目录内执行 git remote add core https://github.com/balderdashy/sails.git git fetch core git merge core/master这三条命令的含义git remote add core ...将上游 Sails 仓库注册为一个名为core的远程仓库若此前已添加过会提示已存在可直接跳到下一步。git fetch core把上游仓库的最新提交与分支引用拉取到本地只更新远程跟踪分支不影响你的工作区。git merge core/master将上游 master 的最新提交合并进你当前所在分支解决可能的冲突后再继续开发。建议在开发前、提 PR 前都各执行一次同步尽量让 PR 基于最新的主干减少与维护者 review 时的冲突。更多 Fork 同步细节可参考 GitHub 官方的 fork-a-repo 帮助文档。四、Code动手写代码以及它的边界同步完成后就可以在你的分支上做增强、修 bug、“do your thang”了。不过 Sails 对“改哪里”有明确的边界划分同样来自 代码提交规范贡献到核心Contributing to coreSails 核心内的各个子模块 API 稳定性参差不齐。Bug 修复补丁永远欢迎但 API 或行为变更必须经过严肃规划遵循上述特性提案流程才能合入。贡献到适配器adapter适配器负责把 Waterline 查询语法翻译成底层数据库语言再把数据库结果映射回 Waterline 期望的响应格式。如果适配器就在 Sails 仓库内按核心规范走如果在别的仓库请把 PR 发到对应仓库。撰写新适配器前先在 npm、Google、GitHub 上彻底搜索确认没有人在做同样的事。贡献到 Hook核心 hooks 遵循核心规范很多核心 hooks 自带 README详尽记录了用途、挂载的方法、触发的事件等实现信息动手前先读。编写自定义 hook 前同样要先搜索确认无重复。贡献到 Generator自定义 generator API 尚未 100% 稳定但已趋于成型。同样记得先搜索避免重复造轮子。无论改动落在哪个模块都要遵守“JavaScript 编写 不改动无关风格 窄聚焦”的准则这是代码能否被合入的第一道关卡。五、Test为你的改动补上测试Mocha npm testSails 要求任何 bug 修复都尽量附带测试新功能更是如此。这一点正是本仓库维护代码质量的基石。5.1 测试框架与运行方式Sails 的测试套件基于 Mocha见 package.json 的 devDependencies 与 scriptsnpm testnpm test会先根据当前 Node 版本决定是否执行 lint再运行npm run custom-tests即node ./node_modules/mocha/bin/mocha -b-b表示遇错即停 bail。如果想单独跑# 仅运行测试不 lint npm run custom-tests # 仅运行代码风格检查基于 ESLintmax-warnings0 npm run lintMocha 的默认参数集中在 test/mocha.opts--reporter spec --recursive --slow 2000 --timeout 18000即使用 spec 报告器、递归扫描测试文件、单测耗时超过 2000ms 提示 slow、超时上限 18000ms。Windows 用户可参考 test/README.md 直接运行npm run custom-tests。5.2 测试目录结构写测试前先找到正确的位置从仓库的 test/ 目录结构可以看到测试被组织为多个子目录unit/单元测试如App.prototype.load.test.js、router.test.js、app.registerAction.test.jsintegration/集成测试如lift.test.js、hook.blueprints.restful.routes.test.js、middleware.session.test.js、www.test.js等覆盖整个应用生命周期与 hook 协同benchmarks/性能基准测试如sails.load.test.js、sails.request.generic.test.jshooks/针对各核心 hook 的专项测试如hooks/blueprints/initialize.test.js、hooks/http/initialize.test.jsfixtures/测试用的样例数据、文件与模板如fixtures/constants.js、fixtures/customHooks.js、fixtures/middleware.jshelpers/用于搭建/拆除 Sails 实例、读取 fixture 的工具逻辑如helpers/sails.js、helpers/router.js、helpers/RouteFactory.helper.js。关于“测什么、不测什么”的完整方法论见同目录下的 编写测试Sails 的目标是让每个可用的特性都有测试同时要避免编写“排他性”测试——例如检查sails new创建了哪些文件可以但断言“只”创建了这些文件就错了因为新增文件不应导致既有测试失败。同理对sails.config.blueprints.rest这类配置的测试应验证配置开启/关闭时 blueprints 的行为是否正确而不是在测试里固化对配置形态的主观判断。六、Pull request提交、推送并发起合并请求完成开发与测试后按以下步骤提交 PR# 1. 查看改动确认只包含本 PR 目标相关的文件 git status git diff # 2. 提交写清提交信息说明修复内容与原因 git commit -am Fix: what you fixed # 3. 推送到你自己的 Fork git push origin your-branch # 4. 在 GitHub 上进入你的 Fork 仓库点击 Compare pull request # 填写清晰的标题与描述说明问题、修复方式、测试情况发起 PRPR 提交后维护者会尽快 review 并给出反馈。两点提醒提交信息与 PR 描述要尽量自解释说明“修了什么、为什么这么修、如何验证”能显著加速 review 流程如果 review 要求改动直接在你的分支上继续提交或按维护者要求 rebase推送后 PR 会自动更新。七、Running your fork with your application用 npm link 实测你的 Fork有时你 fork Sails 不是为了提 PR而是想让自己正在开发的应用直接跑在你自己的 Sails 分支上例如验证一个尚未合入的修复对实际业务的影响。Sails 文档给出了标准的npm link方案。在你的 Sails Fork 本地副本目录中sudo npm link这会把你的 Fork 版本注册为全局可链接的包。在你的 Sails 应用仓库目录中npm link sails这条命令会在应用的node_modules目录中创建一个指向你 Fork 版本的符号链接。效果是运行应用时使用的 Sails 就是你link的那个本地版本$ sails lift这样你就可以在真实应用场景下验证 fork 中的改动确认无误后再走正式的 PR 流程。需要注意的是sudo取决于你的 npm 全局目录权限如果 npm 全局前缀属于当前用户通常可以省略sudo。测试完成后若想恢复官方版本在应用目录执行npm unlink sails并重新npm install即可。八、常见问题与最佳实践小结回顾整个流程给初次贡献者几条可操作的建议先沟通再动手新特性务必基于 ROADMAP.md 并先与维护者对齐不确定是否算补丁时先提 issue。保持 PR 小而聚焦单一目标、最少改动能显著提高合入概率。测试与代码同行bug 修复尽量配测试Mocha提交前跑npm test还要留意 package.json 中的lint脚本ESLint--max-warnings0保持代码风格干净。随时同步上游开发前git fetch core git merge core/master减少冲突。用 npm link 做真实验证在真实应用里跑通你的 fork再提交 PR避免“看起来没问题、跑起来有问题”。Sails 作为一款以 MVC 约定驱动、基于 Express 与 Socket.io 的实时框架其核心质量正是依靠这样一套“补丁/特性分流 测试兜底 窄聚焦 PR”的贡献机制来守护的。遵循本指南提交你的第一个 PR你就在参与维护这个框架的健壮性与可靠性。更多相关阅读代码提交规范、编写测试、测试套件总览。【免费下载链接】sailsRealtime MVC Framework for Node.js项目地址: https://gitcode.com/gh_mirrors/sa/sails创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Sails 框架 Pull Request 提交全指南：从 Fork 到合入的完整实战流程
Sails 框架 Pull Request 提交全指南从 Fork 到合入的完整实战流程【免费下载链接】sailsRealtime MVC Framework for Node.js项目地址: https://gitcode.com/gh_mirrors/sa/sails本文面向希望为 SailsNode.js 实时 MVC 框架贡献代码的开发者系统讲解向 Sails 核心仓库提交 Pull RequestPR的完整操作链路包括贡献前的规范确认、Fork 与 Clone、同步上游更新、编写补丁与测试、发起 PR以及如何用npm link让本地应用直接运行你的 Sails Fork 版本。读完本文你将掌握一套可直接照做的 PR 提交流程并理解 Sails 项目为何要求每份提交都配套测试与代码规范。一、先读官方贡献指南提交 PR 前的准入门槛本指南定位为“官方贡献指南的支撑文档”重点帮助你走通 PR 提交的“操作细节”。在开始之前请先阅读仓库根目录下的 CONTRIBUTING.md当前仓库内该文件已将完整说明指向文档站点“Contributing”栏目并结合 代码提交规范 一文确认你的改动类型。Sails 核心接受的代码贡献只有两种类型提交前务必对号入座补丁Patches小而精准的修复覆盖从错别字到时序问题的各类小改动。例如删除文件顶部一个未使用的require()或者修复一个导致 Travis 上 master 分支测试挂掉的笔误。需要特别警惕即使看似无关紧要的改动只要影响了 Sails 某个已文档化特性的用法或者新增了未文档化的公开函数就不算“补丁”跨多文件改空白、改变量名的“大型重构”同样不算补丁。新特性New features必须是 ROADMAP.md 中已经汇总过的 TODO 项并在随附的 PR 中给出更详细信息。凡是不在 ROADMAP 中的内容都不应作为新特性提交。规范还划出了几条硬性红线见 代码提交规范 的 General rules核心代码只能用 JavaScript 编写支持 maintained LTS 的 JavaScript 语法不能使用 CoffeeScript、TypeScript 或其他需要预编译/转译的语言——包括核心 hooks 与核心 generators 在内。用户态代码随意用 ES6/TS/CoffeeScript 都没问题但提交给 Sails core 的 PR 必须保持一致的 JS 风格。不要顺手“自动格式化代码”或去修复核心已有文件里你认为的风格问题。每个 PR窄聚焦于单一目标改动文件数、改动行数越少越好。不要提交实现或增强特性的 PR除非基于非常明确界定的提案动手前先在 issue/讨论中告知维护者你在做这项工作并保持进度同步否则沉默可能被视作弃权他人会抢先开工。对 Express、Socket.io 等package.json中列出的外部依赖的修改应提交到对应项目仓库Sails 仓库无法受理。提示若对改动是否算“补丁”拿不准请务必在动手前先到 issue tracker 提问或联系核心团队确认——尤其当你计划做一件大事时。没有什么比辛苦写完的代码因与维护者规划不一致而被拒更令人沮丧的了。二、Fork 与 Clone建立你的个人工作副本Sails 是一个实时 MVC 框架lib/index.js 为包入口仓库代码量不小包含 lib/核心实现、test/测试套件、docs/文档等目录。因此直接在主干上开发是不现实的标准流程从 Fork 开始。第一步Fork 仓库。在 GitHub 上打开 Sails 仓库页面点击右上角的 Fork 按钮在你的账户下生成一份副本。第二步Clone 到本地。将你账户下的 Fork 克隆到本地文件系统git clone gitgithub.com:YOUR_USER_NAME/sails.git把YOUR_USER_NAME替换为你的 GitHub 用户名。克隆完成后你会得到一个包含完整源码、测试与文档的本地仓库。建议先跑一遍npm install安装依赖为后续开发与测试做准备。三、Update让 Fork 与上游主干保持同步如果你已经 fork 过一段时间上游 master 可能新增了大量提交。在动手改代码之前先把上游的最新改动合入你的本地分支# 在你的项目目录内执行 git remote add core https://github.com/balderdashy/sails.git git fetch core git merge core/master这三条命令的含义git remote add core ...将上游 Sails 仓库注册为一个名为core的远程仓库若此前已添加过会提示已存在可直接跳到下一步。git fetch core把上游仓库的最新提交与分支引用拉取到本地只更新远程跟踪分支不影响你的工作区。git merge core/master将上游 master 的最新提交合并进你当前所在分支解决可能的冲突后再继续开发。建议在开发前、提 PR 前都各执行一次同步尽量让 PR 基于最新的主干减少与维护者 review 时的冲突。更多 Fork 同步细节可参考 GitHub 官方的 fork-a-repo 帮助文档。四、Code动手写代码以及它的边界同步完成后就可以在你的分支上做增强、修 bug、“do your thang”了。不过 Sails 对“改哪里”有明确的边界划分同样来自 代码提交规范贡献到核心Contributing to coreSails 核心内的各个子模块 API 稳定性参差不齐。Bug 修复补丁永远欢迎但 API 或行为变更必须经过严肃规划遵循上述特性提案流程才能合入。贡献到适配器adapter适配器负责把 Waterline 查询语法翻译成底层数据库语言再把数据库结果映射回 Waterline 期望的响应格式。如果适配器就在 Sails 仓库内按核心规范走如果在别的仓库请把 PR 发到对应仓库。撰写新适配器前先在 npm、Google、GitHub 上彻底搜索确认没有人在做同样的事。贡献到 Hook核心 hooks 遵循核心规范很多核心 hooks 自带 README详尽记录了用途、挂载的方法、触发的事件等实现信息动手前先读。编写自定义 hook 前同样要先搜索确认无重复。贡献到 Generator自定义 generator API 尚未 100% 稳定但已趋于成型。同样记得先搜索避免重复造轮子。无论改动落在哪个模块都要遵守“JavaScript 编写 不改动无关风格 窄聚焦”的准则这是代码能否被合入的第一道关卡。五、Test为你的改动补上测试Mocha npm testSails 要求任何 bug 修复都尽量附带测试新功能更是如此。这一点正是本仓库维护代码质量的基石。5.1 测试框架与运行方式Sails 的测试套件基于 Mocha见 package.json 的 devDependencies 与 scriptsnpm testnpm test会先根据当前 Node 版本决定是否执行 lint再运行npm run custom-tests即node ./node_modules/mocha/bin/mocha -b-b表示遇错即停 bail。如果想单独跑# 仅运行测试不 lint npm run custom-tests # 仅运行代码风格检查基于 ESLintmax-warnings0 npm run lintMocha 的默认参数集中在 test/mocha.opts--reporter spec --recursive --slow 2000 --timeout 18000即使用 spec 报告器、递归扫描测试文件、单测耗时超过 2000ms 提示 slow、超时上限 18000ms。Windows 用户可参考 test/README.md 直接运行npm run custom-tests。5.2 测试目录结构写测试前先找到正确的位置从仓库的 test/ 目录结构可以看到测试被组织为多个子目录unit/单元测试如App.prototype.load.test.js、router.test.js、app.registerAction.test.jsintegration/集成测试如lift.test.js、hook.blueprints.restful.routes.test.js、middleware.session.test.js、www.test.js等覆盖整个应用生命周期与 hook 协同benchmarks/性能基准测试如sails.load.test.js、sails.request.generic.test.jshooks/针对各核心 hook 的专项测试如hooks/blueprints/initialize.test.js、hooks/http/initialize.test.jsfixtures/测试用的样例数据、文件与模板如fixtures/constants.js、fixtures/customHooks.js、fixtures/middleware.jshelpers/用于搭建/拆除 Sails 实例、读取 fixture 的工具逻辑如helpers/sails.js、helpers/router.js、helpers/RouteFactory.helper.js。关于“测什么、不测什么”的完整方法论见同目录下的 编写测试Sails 的目标是让每个可用的特性都有测试同时要避免编写“排他性”测试——例如检查sails new创建了哪些文件可以但断言“只”创建了这些文件就错了因为新增文件不应导致既有测试失败。同理对sails.config.blueprints.rest这类配置的测试应验证配置开启/关闭时 blueprints 的行为是否正确而不是在测试里固化对配置形态的主观判断。六、Pull request提交、推送并发起合并请求完成开发与测试后按以下步骤提交 PR# 1. 查看改动确认只包含本 PR 目标相关的文件 git status git diff # 2. 提交写清提交信息说明修复内容与原因 git commit -am Fix: what you fixed # 3. 推送到你自己的 Fork git push origin your-branch # 4. 在 GitHub 上进入你的 Fork 仓库点击 Compare pull request # 填写清晰的标题与描述说明问题、修复方式、测试情况发起 PRPR 提交后维护者会尽快 review 并给出反馈。两点提醒提交信息与 PR 描述要尽量自解释说明“修了什么、为什么这么修、如何验证”能显著加速 review 流程如果 review 要求改动直接在你的分支上继续提交或按维护者要求 rebase推送后 PR 会自动更新。七、Running your fork with your application用 npm link 实测你的 Fork有时你 fork Sails 不是为了提 PR而是想让自己正在开发的应用直接跑在你自己的 Sails 分支上例如验证一个尚未合入的修复对实际业务的影响。Sails 文档给出了标准的npm link方案。在你的 Sails Fork 本地副本目录中sudo npm link这会把你的 Fork 版本注册为全局可链接的包。在你的 Sails 应用仓库目录中npm link sails这条命令会在应用的node_modules目录中创建一个指向你 Fork 版本的符号链接。效果是运行应用时使用的 Sails 就是你link的那个本地版本$ sails lift这样你就可以在真实应用场景下验证 fork 中的改动确认无误后再走正式的 PR 流程。需要注意的是sudo取决于你的 npm 全局目录权限如果 npm 全局前缀属于当前用户通常可以省略sudo。测试完成后若想恢复官方版本在应用目录执行npm unlink sails并重新npm install即可。八、常见问题与最佳实践小结回顾整个流程给初次贡献者几条可操作的建议先沟通再动手新特性务必基于 ROADMAP.md 并先与维护者对齐不确定是否算补丁时先提 issue。保持 PR 小而聚焦单一目标、最少改动能显著提高合入概率。测试与代码同行bug 修复尽量配测试Mocha提交前跑npm test还要留意 package.json 中的lint脚本ESLint--max-warnings0保持代码风格干净。随时同步上游开发前git fetch core git merge core/master减少冲突。用 npm link 做真实验证在真实应用里跑通你的 fork再提交 PR避免“看起来没问题、跑起来有问题”。Sails 作为一款以 MVC 约定驱动、基于 Express 与 Socket.io 的实时框架其核心质量正是依靠这样一套“补丁/特性分流 测试兜底 窄聚焦 PR”的贡献机制来守护的。遵循本指南提交你的第一个 PR你就在参与维护这个框架的健壮性与可靠性。更多相关阅读代码提交规范、编写测试、测试套件总览。【免费下载链接】sailsRealtime MVC Framework for Node.js项目地址: https://gitcode.com/gh_mirrors/sa/sails创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考