戰(zhàn)流程)
Sails 框架 Pull Request 提交全指南從 Fork 到合入的完整實(shí)戰(zhàn)流程【免費(fèi)下載鏈接】sailsRealtime MVC Framework for Node.js項(xiàng)目地址: https://gitcode.com/gh_mirrors/sa/sails本文面向希望為 SailsNode.js 實(shí)時(shí) MVC 框架貢獻(xiàn)代碼的開(kāi)發(fā)者系統(tǒng)講解向 Sails 核心倉(cāng)庫(kù)提交 Pull RequestPR的完整操作鏈路包括貢獻(xiàn)前的規(guī)范確認(rèn)、Fork 與 Clone、同步上游更新、編寫(xiě)補(bǔ)丁與測(cè)試、發(fā)起 PR以及如何用npm link讓本地應(yīng)用直接運(yùn)行你的 Sails Fork 版本。讀完本文你將掌握一套可直接照做的 PR 提交流程并理解 Sails 項(xiàng)目為何要求每份提交都配套測(cè)試與代碼規(guī)范。一、先讀官方貢獻(xiàn)指南提交 PR 前的準(zhǔn)入門(mén)檻本指南定位為“官方貢獻(xiàn)指南的支撐文檔”重點(diǎn)幫助你走通 PR 提交的“操作細(xì)節(jié)”。在開(kāi)始之前請(qǐng)先閱讀倉(cāng)庫(kù)根目錄下的 CONTRIBUTING.md當(dāng)前倉(cāng)庫(kù)內(nèi)該文件已將完整說(shuō)明指向文檔站點(diǎn)“Contributing”欄目并結(jié)合 代碼提交規(guī)范 一文確認(rèn)你的改動(dòng)類(lèi)型。Sails 核心接受的代碼貢獻(xiàn)只有兩種類(lèi)型提交前務(wù)必對(duì)號(hào)入座補(bǔ)丁Patches小而精準(zhǔn)的修復(fù)覆蓋從錯(cuò)別字到時(shí)序問(wèn)題的各類(lèi)小改動(dòng)。例如刪除文件頂部一個(gè)未使用的require()或者修復(fù)一個(gè)導(dǎo)致 Travis 上 master 分支測(cè)試掛掉的筆誤。需要特別警惕即使看似無(wú)關(guān)緊要的改動(dòng)只要影響了 Sails 某個(gè)已文檔化特性的用法或者新增了未文檔化的公開(kāi)函數(shù)就不算“補(bǔ)丁”跨多文件改空白、改變量名的“大型重構(gòu)”同樣不算補(bǔ)丁。新特性New features必須是 ROADMAP.md 中已經(jīng)匯總過(guò)的 TODO 項(xiàng)并在隨附的 PR 中給出更詳細(xì)信息。凡是不在 ROADMAP 中的內(nèi)容都不應(yīng)作為新特性提交。規(guī)范還劃出了幾條硬性紅線見(jiàn) 代碼提交規(guī)范 的 General rules核心代碼只能用 JavaScript 編寫(xiě)支持 maintained LTS 的 JavaScript 語(yǔ)法不能使用 CoffeeScript、TypeScript 或其他需要預(yù)編譯/轉(zhuǎn)譯的語(yǔ)言——包括核心 hooks 與核心 generators 在內(nèi)。用戶(hù)態(tài)代碼隨意用 ES6/TS/CoffeeScript 都沒(méi)問(wèn)題但提交給 Sails core 的 PR 必須保持一致的 JS 風(fēng)格。不要順手“自動(dòng)格式化代碼”或去修復(fù)核心已有文件里你認(rèn)為的風(fēng)格問(wèn)題。每個(gè) PR窄聚焦于單一目標(biāo)改動(dòng)文件數(shù)、改動(dòng)行數(shù)越少越好。不要提交實(shí)現(xiàn)或增強(qiáng)特性的 PR除非基于非常明確界定的提案動(dòng)手前先在 issue/討論中告知維護(hù)者你在做這項(xiàng)工作并保持進(jìn)度同步否則沉默可能被視作棄權(quán)他人會(huì)搶先開(kāi)工。對(duì) Express、Socket.io 等package.json中列出的外部依賴(lài)的修改應(yīng)提交到對(duì)應(yīng)項(xiàng)目倉(cāng)庫(kù)Sails 倉(cāng)庫(kù)無(wú)法受理。提示若對(duì)改動(dòng)是否算“補(bǔ)丁”拿不準(zhǔn)請(qǐng)務(wù)必在動(dòng)手前先到 issue tracker 提問(wèn)或聯(lián)系核心團(tuán)隊(duì)確認(rèn)——尤其當(dāng)你計(jì)劃做一件大事時(shí)。沒(méi)有什么比辛苦寫(xiě)完的代碼因與維護(hù)者規(guī)劃不一致而被拒更令人沮喪的了。二、Fork 與 Clone建立你的個(gè)人工作副本Sails 是一個(gè)實(shí)時(shí) MVC 框架lib/index.js 為包入口倉(cāng)庫(kù)代碼量不小包含 lib/核心實(shí)現(xiàn)、test/測(cè)試套件、docs/文檔等目錄。因此直接在主干上開(kāi)發(fā)是不現(xiàn)實(shí)的標(biāo)準(zhǔn)流程從 Fork 開(kāi)始。第一步Fork 倉(cāng)庫(kù)。在 GitHub 上打開(kāi) Sails 倉(cāng)庫(kù)頁(yè)面點(diǎn)擊右上角的 Fork 按鈕在你的賬戶(hù)下生成一份副本。第二步Clone 到本地。將你賬戶(hù)下的 Fork 克隆到本地文件系統(tǒng)git clone gitgithub.com:YOUR_USER_NAME/sails.git把YOUR_USER_NAME替換為你的 GitHub 用戶(hù)名?？寺⊥瓿珊竽銜?huì)得到一個(gè)包含完整源碼、測(cè)試與文檔的本地倉(cāng)庫(kù)。建議先跑一遍npm install安裝依賴(lài)為后續(xù)開(kāi)發(fā)與測(cè)試做準(zhǔn)備。三、Update讓 Fork 與上游主干保持同步如果你已經(jīng) fork 過(guò)一段時(shí)間上游 master 可能新增了大量提交。在動(dòng)手改代碼之前先把上游的最新改動(dòng)合入你的本地分支# 在你的項(xiàng)目目錄內(nèi)執(zhí)行 git remote add core https://github.com/balderdashy/sails.git git fetch core git merge core/master這三條命令的含義git remote add core ...將上游 Sails 倉(cāng)庫(kù)注冊(cè)為一個(gè)名為core的遠(yuǎn)程倉(cāng)庫(kù)若此前已添加過(guò)會(huì)提示已存在可直接跳到下一步。git fetch core把上游倉(cāng)庫(kù)的最新提交與分支引用拉取到本地只更新遠(yuǎn)程跟蹤分支不影響你的工作區(qū)。git merge core/master將上游 master 的最新提交合并進(jìn)你當(dāng)前所在分支解決可能的沖突后再繼續(xù)開(kāi)發(fā)。建議在開(kāi)發(fā)前、提 PR 前都各執(zhí)行一次同步盡量讓 PR 基于最新的主干減少與維護(hù)者 review 時(shí)的沖突。更多 Fork 同步細(xì)節(jié)可參考 GitHub 官方的 fork-a-repo 幫助文檔。四、Code動(dòng)手寫(xiě)代碼以及它的邊界同步完成后就可以在你的分支上做增強(qiáng)、修 bug、“do your thang”了。不過(guò) Sails 對(duì)“改哪里”有明確的邊界劃分同樣來(lái)自 代碼提交規(guī)范貢獻(xiàn)到核心Contributing to coreSails 核心內(nèi)的各個(gè)子模塊 API 穩(wěn)定性參差不齊。Bug 修復(fù)補(bǔ)丁永遠(yuǎn)歡迎但 API 或行為變更必須經(jīng)過(guò)嚴(yán)肅規(guī)劃遵循上述特性提案流程才能合入。貢獻(xiàn)到適配器adapter適配器負(fù)責(zé)把 Waterline 查詢(xún)語(yǔ)法翻譯成底層數(shù)據(jù)庫(kù)語(yǔ)言再把數(shù)據(jù)庫(kù)結(jié)果映射回 Waterline 期望的響應(yīng)格式。如果適配器就在 Sails 倉(cāng)庫(kù)內(nèi)按核心規(guī)范走如果在別的倉(cāng)庫(kù)請(qǐng)把 PR 發(fā)到對(duì)應(yīng)倉(cāng)庫(kù)。撰寫(xiě)新適配器前先在 npm、Google、GitHub 上徹底搜索確認(rèn)沒(méi)有人在做同樣的事。貢獻(xiàn)到 Hook核心 hooks 遵循核心規(guī)范很多核心 hooks 自帶 README詳盡記錄了用途、掛載的方法、觸發(fā)的事件等實(shí)現(xiàn)信息動(dòng)手前先讀。編寫(xiě)自定義 hook 前同樣要先搜索確認(rèn)無(wú)重復(fù)。貢獻(xiàn)到 Generator自定義 generator API 尚未 100% 穩(wěn)定但已趨于成型。同樣記得先搜索避免重復(fù)造輪子。無(wú)論改動(dòng)落在哪個(gè)模塊都要遵守“JavaScript 編寫(xiě) 不改動(dòng)無(wú)關(guān)風(fēng)格 窄聚焦”的準(zhǔn)則這是代碼能否被合入的第一道關(guān)卡。五、Test為你的改動(dòng)補(bǔ)上測(cè)試Mocha npm testSails 要求任何 bug 修復(fù)都盡量附帶測(cè)試新功能更是如此。這一點(diǎn)正是本倉(cāng)庫(kù)維護(hù)代碼質(zhì)量的基石。5.1 測(cè)試框架與運(yùn)行方式Sails 的測(cè)試套件基于 Mocha見(jiàn) package.json 的 devDependencies 與 scriptsnpm testnpm test會(huì)先根據(jù)當(dāng)前 Node 版本決定是否執(zhí)行 lint再運(yùn)行npm run custom-tests即node ./node_modules/mocha/bin/mocha -b-b表示遇錯(cuò)即停 bail。如果想單獨(dú)跑# 僅運(yùn)行測(cè)試不 lint npm run custom-tests # 僅運(yùn)行代碼風(fēng)格檢查基于 ESLintmax-warnings0 npm run lintMocha 的默認(rèn)參數(shù)集中在 test/mocha.opts--reporter spec --recursive --slow 2000 --timeout 18000即使用 spec 報(bào)告器、遞歸掃描測(cè)試文件、單測(cè)耗時(shí)超過(guò) 2000ms 提示 slow、超時(shí)上限 18000ms。Windows 用戶(hù)可參考 test/README.md 直接運(yùn)行npm run custom-tests。5.2 測(cè)試目錄結(jié)構(gòu)寫(xiě)測(cè)試前先找到正確的位置從倉(cāng)庫(kù)的 test/ 目錄結(jié)構(gòu)可以看到測(cè)試被組織為多個(gè)子目錄unit/單元測(cè)試如App.prototype.load.test.js、router.test.js、app.registerAction.test.jsintegration/集成測(cè)試如lift.test.js、hook.blueprints.restful.routes.test.js、middleware.session.test.js、www.test.js等覆蓋整個(gè)應(yīng)用生命周期與 hook 協(xié)同benchmarks/性能基準(zhǔn)測(cè)試如sails.load.test.js、sails.request.generic.test.jshooks/針對(duì)各核心 hook 的專(zhuān)項(xiàng)測(cè)試如hooks/blueprints/initialize.test.js、hooks/http/initialize.test.jsfixtures/測(cè)試用的樣例數(shù)據(jù)、文件與模板如fixtures/constants.js、fixtures/customHooks.js、fixtures/middleware.jshelpers/用于搭建/拆除 Sails 實(shí)例、讀取 fixture 的工具邏輯如helpers/sails.js、helpers/router.js、helpers/RouteFactory.helper.js。關(guān)于“測(cè)什么、不測(cè)什么”的完整方法論見(jiàn)同目錄下的 編寫(xiě)測(cè)試Sails 的目標(biāo)是讓每個(gè)可用的特性都有測(cè)試同時(shí)要避免編寫(xiě)“排他性”測(cè)試——例如檢查sails new創(chuàng)建了哪些文件可以但斷言“只”創(chuàng)建了這些文件就錯(cuò)了因?yàn)樾略鑫募粦?yīng)導(dǎo)致既有測(cè)試失敗。同理對(duì)sails.config.blueprints.rest這類(lèi)配置的測(cè)試應(yīng)驗(yàn)證配置開(kāi)啟/關(guān)閉時(shí) blueprints 的行為是否正確而不是在測(cè)試?yán)锕袒瘜?duì)配置形態(tài)的主觀判斷。六、Pull request提交、推送并發(fā)起合并請(qǐng)求完成開(kāi)發(fā)與測(cè)試后按以下步驟提交 PR# 1. 查看改動(dòng)確認(rèn)只包含本 PR 目標(biāo)相關(guān)的文件 git status git diff # 2. 提交寫(xiě)清提交信息說(shuō)明修復(fù)內(nèi)容與原因 git commit -am Fix: what you fixed # 3. 推送到你自己的 Fork git push origin your-branch # 4. 在 GitHub 上進(jìn)入你的 Fork 倉(cāng)庫(kù)點(diǎn)擊 Compare pull request # 填寫(xiě)清晰的標(biāo)題與描述說(shuō)明問(wèn)題、修復(fù)方式、測(cè)試情況發(fā)起 PRPR 提交后維護(hù)者會(huì)盡快 review 并給出反饋。兩點(diǎn)提醒提交信息與 PR 描述要盡量自解釋說(shuō)明“修了什么、為什么這么修、如何驗(yàn)證”能顯著加速 review 流程如果 review 要求改動(dòng)直接在你的分支上繼續(xù)提交或按維護(hù)者要求 rebase推送后 PR 會(huì)自動(dòng)更新。七、Running your fork with your application用 npm link 實(shí)測(cè)你的 Fork有時(shí)你 fork Sails 不是為了提 PR而是想讓自己正在開(kāi)發(fā)的應(yīng)用直接跑在你自己的 Sails 分支上例如驗(yàn)證一個(gè)尚未合入的修復(fù)對(duì)實(shí)際業(yè)務(wù)的影響。Sails 文檔給出了標(biāo)準(zhǔn)的npm link方案。在你的 Sails Fork 本地副本目錄中sudo npm link這會(huì)把你的 Fork 版本注冊(cè)為全局可鏈接的包。在你的 Sails 應(yīng)用倉(cāng)庫(kù)目錄中npm link sails這條命令會(huì)在應(yīng)用的node_modules目錄中創(chuàng)建一個(gè)指向你 Fork 版本的符號(hào)鏈接。效果是運(yùn)行應(yīng)用時(shí)使用的 Sails 就是你link的那個(gè)本地版本$ sails lift這樣你就可以在真實(shí)應(yīng)用場(chǎng)景下驗(yàn)證 fork 中的改動(dòng)確認(rèn)無(wú)誤后再走正式的 PR 流程。需要注意的是sudo取決于你的 npm 全局目錄權(quán)限如果 npm 全局前綴屬于當(dāng)前用戶(hù)通?？梢允÷詓udo。測(cè)試完成后若想恢復(fù)官方版本在應(yīng)用目錄執(zhí)行npm unlink sails并重新npm install即可。八、常見(jiàn)問(wèn)題與最佳實(shí)踐小結(jié)回顧整個(gè)流程給初次貢獻(xiàn)者幾條可操作的建議先溝通再動(dòng)手新特性務(wù)必基于 ROADMAP.md 并先與維護(hù)者對(duì)齊不確定是否算補(bǔ)丁時(shí)先提 issue。保持 PR 小而聚焦單一目標(biāo)、最少改動(dòng)能顯著提高合入概率。測(cè)試與代碼同行bug 修復(fù)盡量配測(cè)試Mocha提交前跑npm test還要留意 package.json 中的lint腳本ESLint--max-warnings0保持代碼風(fēng)格干凈。隨時(shí)同步上游開(kāi)發(fā)前git fetch core git merge core/master減少?zèng)_突。用 npm link 做真實(shí)驗(yàn)證在真實(shí)應(yīng)用里跑通你的 fork再提交 PR避免“看起來(lái)沒(méi)問(wèn)題、跑起來(lái)有問(wèn)題”。Sails 作為一款以 MVC 約定驅(qū)動(dòng)、基于 Express 與 Socket.io 的實(shí)時(shí)框架其核心質(zhì)量正是依靠這樣一套“補(bǔ)丁/特性分流 測(cè)試兜底 窄聚焦 PR”的貢獻(xiàn)機(jī)制來(lái)守護(hù)的。遵循本指南提交你的第一個(gè) PR你就在參與維護(hù)這個(gè)框架的健壯性與可靠性。更多相關(guān)閱讀代碼提交規(guī)范、編寫(xiě)測(cè)試、測(cè)試套件總覽?！久赓M(fèi)下載鏈接】sailsRealtime MVC Framework for Node.js項(xiàng)目地址: https://gitcode.com/gh_mirrors/sa/sails創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 Sails 框架 Pull Request 提交全指南：從 Fork 到合入的完整實(shí)戰(zhàn)流程
Sails 框架 Pull Request 提交全指南從 Fork 到合入的完整實(shí)戰(zhàn)流程【免費(fèi)下載鏈接】sailsRealtime MVC Framework for Node.js項(xiàng)目地址: https://gitcode.com/gh_mirrors/sa/sails本文面向希望為 SailsNode.js 實(shí)時(shí) MVC 框架貢獻(xiàn)代碼的開(kāi)發(fā)者系統(tǒng)講解向 Sails 核心倉(cāng)庫(kù)提交 Pull RequestPR的完整操作鏈路包括貢獻(xiàn)前的規(guī)范確認(rèn)、Fork 與 Clone、同步上游更新、編寫(xiě)補(bǔ)丁與測(cè)試、發(fā)起 PR以及如何用npm link讓本地應(yīng)用直接運(yùn)行你的 Sails Fork 版本。讀完本文你將掌握一套可直接照做的 PR 提交流程并理解 Sails 項(xiàng)目為何要求每份提交都配套測(cè)試與代碼規(guī)范。一、先讀官方貢獻(xiàn)指南提交 PR 前的準(zhǔn)入門(mén)檻本指南定位為“官方貢獻(xiàn)指南的支撐文檔”重點(diǎn)幫助你走通 PR 提交的“操作細(xì)節(jié)”。在開(kāi)始之前請(qǐng)先閱讀倉(cāng)庫(kù)根目錄下的 CONTRIBUTING.md當(dāng)前倉(cāng)庫(kù)內(nèi)該文件已將完整說(shuō)明指向文檔站點(diǎn)“Contributing”欄目并結(jié)合 代碼提交規(guī)范 一文確認(rèn)你的改動(dòng)類(lèi)型。Sails 核心接受的代碼貢獻(xiàn)只有兩種類(lèi)型提交前務(wù)必對(duì)號(hào)入座補(bǔ)丁Patches小而精準(zhǔn)的修復(fù)覆蓋從錯(cuò)別字到時(shí)序問(wèn)題的各類(lèi)小改動(dòng)。例如刪除文件頂部一個(gè)未使用的require()或者修復(fù)一個(gè)導(dǎo)致 Travis 上 master 分支測(cè)試掛掉的筆誤。需要特別警惕即使看似無(wú)關(guān)緊要的改動(dòng)只要影響了 Sails 某個(gè)已文檔化特性的用法或者新增了未文檔化的公開(kāi)函數(shù)就不算“補(bǔ)丁”跨多文件改空白、改變量名的“大型重構(gòu)”同樣不算補(bǔ)丁。新特性New features必須是 ROADMAP.md 中已經(jīng)匯總過(guò)的 TODO 項(xiàng)并在隨附的 PR 中給出更詳細(xì)信息。凡是不在 ROADMAP 中的內(nèi)容都不應(yīng)作為新特性提交。規(guī)范還劃出了幾條硬性紅線見(jiàn) 代碼提交規(guī)范 的 General rules核心代碼只能用 JavaScript 編寫(xiě)支持 maintained LTS 的 JavaScript 語(yǔ)法不能使用 CoffeeScript、TypeScript 或其他需要預(yù)編譯/轉(zhuǎn)譯的語(yǔ)言——包括核心 hooks 與核心 generators 在內(nèi)。用戶(hù)態(tài)代碼隨意用 ES6/TS/CoffeeScript 都沒(méi)問(wèn)題但提交給 Sails core 的 PR 必須保持一致的 JS 風(fēng)格。不要順手“自動(dòng)格式化代碼”或去修復(fù)核心已有文件里你認(rèn)為的風(fēng)格問(wèn)題。每個(gè) PR窄聚焦于單一目標(biāo)改動(dòng)文件數(shù)、改動(dòng)行數(shù)越少越好。不要提交實(shí)現(xiàn)或增強(qiáng)特性的 PR除非基于非常明確界定的提案動(dòng)手前先在 issue/討論中告知維護(hù)者你在做這項(xiàng)工作并保持進(jìn)度同步否則沉默可能被視作棄權(quán)他人會(huì)搶先開(kāi)工。對(duì) Express、Socket.io 等package.json中列出的外部依賴(lài)的修改應(yīng)提交到對(duì)應(yīng)項(xiàng)目倉(cāng)庫(kù)Sails 倉(cāng)庫(kù)無(wú)法受理。提示若對(duì)改動(dòng)是否算“補(bǔ)丁”拿不準(zhǔn)請(qǐng)務(wù)必在動(dòng)手前先到 issue tracker 提問(wèn)或聯(lián)系核心團(tuán)隊(duì)確認(rèn)——尤其當(dāng)你計(jì)劃做一件大事時(shí)。沒(méi)有什么比辛苦寫(xiě)完的代碼因與維護(hù)者規(guī)劃不一致而被拒更令人沮喪的了。二、Fork 與 Clone建立你的個(gè)人工作副本Sails 是一個(gè)實(shí)時(shí) MVC 框架lib/index.js 為包入口倉(cāng)庫(kù)代碼量不小包含 lib/核心實(shí)現(xiàn)、test/測(cè)試套件、docs/文檔等目錄。因此直接在主干上開(kāi)發(fā)是不現(xiàn)實(shí)的標(biāo)準(zhǔn)流程從 Fork 開(kāi)始。第一步Fork 倉(cāng)庫(kù)。在 GitHub 上打開(kāi) Sails 倉(cāng)庫(kù)頁(yè)面點(diǎn)擊右上角的 Fork 按鈕在你的賬戶(hù)下生成一份副本。第二步Clone 到本地。將你賬戶(hù)下的 Fork 克隆到本地文件系統(tǒng)git clone gitgithub.com:YOUR_USER_NAME/sails.git把YOUR_USER_NAME替換為你的 GitHub 用戶(hù)名?？寺⊥瓿珊竽銜?huì)得到一個(gè)包含完整源碼、測(cè)試與文檔的本地倉(cāng)庫(kù)。建議先跑一遍npm install安裝依賴(lài)為后續(xù)開(kāi)發(fā)與測(cè)試做準(zhǔn)備。三、Update讓 Fork 與上游主干保持同步如果你已經(jīng) fork 過(guò)一段時(shí)間上游 master 可能新增了大量提交。在動(dòng)手改代碼之前先把上游的最新改動(dòng)合入你的本地分支# 在你的項(xiàng)目目錄內(nèi)執(zhí)行 git remote add core https://github.com/balderdashy/sails.git git fetch core git merge core/master這三條命令的含義git remote add core ...將上游 Sails 倉(cāng)庫(kù)注冊(cè)為一個(gè)名為core的遠(yuǎn)程倉(cāng)庫(kù)若此前已添加過(guò)會(huì)提示已存在可直接跳到下一步。git fetch core把上游倉(cāng)庫(kù)的最新提交與分支引用拉取到本地只更新遠(yuǎn)程跟蹤分支不影響你的工作區(qū)。git merge core/master將上游 master 的最新提交合并進(jìn)你當(dāng)前所在分支解決可能的沖突后再繼續(xù)開(kāi)發(fā)。建議在開(kāi)發(fā)前、提 PR 前都各執(zhí)行一次同步盡量讓 PR 基于最新的主干減少與維護(hù)者 review 時(shí)的沖突。更多 Fork 同步細(xì)節(jié)可參考 GitHub 官方的 fork-a-repo 幫助文檔。四、Code動(dòng)手寫(xiě)代碼以及它的邊界同步完成后就可以在你的分支上做增強(qiáng)、修 bug、“do your thang”了。不過(guò) Sails 對(duì)“改哪里”有明確的邊界劃分同樣來(lái)自 代碼提交規(guī)范貢獻(xiàn)到核心Contributing to coreSails 核心內(nèi)的各個(gè)子模塊 API 穩(wěn)定性參差不齊。Bug 修復(fù)補(bǔ)丁永遠(yuǎn)歡迎但 API 或行為變更必須經(jīng)過(guò)嚴(yán)肅規(guī)劃遵循上述特性提案流程才能合入。貢獻(xiàn)到適配器adapter適配器負(fù)責(zé)把 Waterline 查詢(xún)語(yǔ)法翻譯成底層數(shù)據(jù)庫(kù)語(yǔ)言再把數(shù)據(jù)庫(kù)結(jié)果映射回 Waterline 期望的響應(yīng)格式。如果適配器就在 Sails 倉(cāng)庫(kù)內(nèi)按核心規(guī)范走如果在別的倉(cāng)庫(kù)請(qǐng)把 PR 發(fā)到對(duì)應(yīng)倉(cāng)庫(kù)。撰寫(xiě)新適配器前先在 npm、Google、GitHub 上徹底搜索確認(rèn)沒(méi)有人在做同樣的事。貢獻(xiàn)到 Hook核心 hooks 遵循核心規(guī)范很多核心 hooks 自帶 README詳盡記錄了用途、掛載的方法、觸發(fā)的事件等實(shí)現(xiàn)信息動(dòng)手前先讀。編寫(xiě)自定義 hook 前同樣要先搜索確認(rèn)無(wú)重復(fù)。貢獻(xiàn)到 Generator自定義 generator API 尚未 100% 穩(wěn)定但已趨于成型。同樣記得先搜索避免重復(fù)造輪子。無(wú)論改動(dòng)落在哪個(gè)模塊都要遵守“JavaScript 編寫(xiě) 不改動(dòng)無(wú)關(guān)風(fēng)格 窄聚焦”的準(zhǔn)則這是代碼能否被合入的第一道關(guān)卡。五、Test為你的改動(dòng)補(bǔ)上測(cè)試Mocha npm testSails 要求任何 bug 修復(fù)都盡量附帶測(cè)試新功能更是如此。這一點(diǎn)正是本倉(cāng)庫(kù)維護(hù)代碼質(zhì)量的基石。5.1 測(cè)試框架與運(yùn)行方式Sails 的測(cè)試套件基于 Mocha見(jiàn) package.json 的 devDependencies 與 scriptsnpm testnpm test會(huì)先根據(jù)當(dāng)前 Node 版本決定是否執(zhí)行 lint再運(yùn)行npm run custom-tests即node ./node_modules/mocha/bin/mocha -b-b表示遇錯(cuò)即停 bail。如果想單獨(dú)跑# 僅運(yùn)行測(cè)試不 lint npm run custom-tests # 僅運(yùn)行代碼風(fēng)格檢查基于 ESLintmax-warnings0 npm run lintMocha 的默認(rèn)參數(shù)集中在 test/mocha.opts--reporter spec --recursive --slow 2000 --timeout 18000即使用 spec 報(bào)告器、遞歸掃描測(cè)試文件、單測(cè)耗時(shí)超過(guò) 2000ms 提示 slow、超時(shí)上限 18000ms。Windows 用戶(hù)可參考 test/README.md 直接運(yùn)行npm run custom-tests。5.2 測(cè)試目錄結(jié)構(gòu)寫(xiě)測(cè)試前先找到正確的位置從倉(cāng)庫(kù)的 test/ 目錄結(jié)構(gòu)可以看到測(cè)試被組織為多個(gè)子目錄unit/單元測(cè)試如App.prototype.load.test.js、router.test.js、app.registerAction.test.jsintegration/集成測(cè)試如lift.test.js、hook.blueprints.restful.routes.test.js、middleware.session.test.js、www.test.js等覆蓋整個(gè)應(yīng)用生命周期與 hook 協(xié)同benchmarks/性能基準(zhǔn)測(cè)試如sails.load.test.js、sails.request.generic.test.jshooks/針對(duì)各核心 hook 的專(zhuān)項(xiàng)測(cè)試如hooks/blueprints/initialize.test.js、hooks/http/initialize.test.jsfixtures/測(cè)試用的樣例數(shù)據(jù)、文件與模板如fixtures/constants.js、fixtures/customHooks.js、fixtures/middleware.jshelpers/用于搭建/拆除 Sails 實(shí)例、讀取 fixture 的工具邏輯如helpers/sails.js、helpers/router.js、helpers/RouteFactory.helper.js。關(guān)于“測(cè)什么、不測(cè)什么”的完整方法論見(jiàn)同目錄下的 編寫(xiě)測(cè)試Sails 的目標(biāo)是讓每個(gè)可用的特性都有測(cè)試同時(shí)要避免編寫(xiě)“排他性”測(cè)試——例如檢查sails new創(chuàng)建了哪些文件可以但斷言“只”創(chuàng)建了這些文件就錯(cuò)了因?yàn)樾略鑫募粦?yīng)導(dǎo)致既有測(cè)試失敗。同理對(duì)sails.config.blueprints.rest這類(lèi)配置的測(cè)試應(yīng)驗(yàn)證配置開(kāi)啟/關(guān)閉時(shí) blueprints 的行為是否正確而不是在測(cè)試?yán)锕袒瘜?duì)配置形態(tài)的主觀判斷。六、Pull request提交、推送并發(fā)起合并請(qǐng)求完成開(kāi)發(fā)與測(cè)試后按以下步驟提交 PR# 1. 查看改動(dòng)確認(rèn)只包含本 PR 目標(biāo)相關(guān)的文件 git status git diff # 2. 提交寫(xiě)清提交信息說(shuō)明修復(fù)內(nèi)容與原因 git commit -am Fix: what you fixed # 3. 推送到你自己的 Fork git push origin your-branch # 4. 在 GitHub 上進(jìn)入你的 Fork 倉(cāng)庫(kù)點(diǎn)擊 Compare pull request # 填寫(xiě)清晰的標(biāo)題與描述說(shuō)明問(wèn)題、修復(fù)方式、測(cè)試情況發(fā)起 PRPR 提交后維護(hù)者會(huì)盡快 review 并給出反饋。兩點(diǎn)提醒提交信息與 PR 描述要盡量自解釋說(shuō)明“修了什么、為什么這么修、如何驗(yàn)證”能顯著加速 review 流程如果 review 要求改動(dòng)直接在你的分支上繼續(xù)提交或按維護(hù)者要求 rebase推送后 PR 會(huì)自動(dòng)更新。七、Running your fork with your application用 npm link 實(shí)測(cè)你的 Fork有時(shí)你 fork Sails 不是為了提 PR而是想讓自己正在開(kāi)發(fā)的應(yīng)用直接跑在你自己的 Sails 分支上例如驗(yàn)證一個(gè)尚未合入的修復(fù)對(duì)實(shí)際業(yè)務(wù)的影響。Sails 文檔給出了標(biāo)準(zhǔn)的npm link方案。在你的 Sails Fork 本地副本目錄中sudo npm link這會(huì)把你的 Fork 版本注冊(cè)為全局可鏈接的包。在你的 Sails 應(yīng)用倉(cāng)庫(kù)目錄中npm link sails這條命令會(huì)在應(yīng)用的node_modules目錄中創(chuàng)建一個(gè)指向你 Fork 版本的符號(hào)鏈接。效果是運(yùn)行應(yīng)用時(shí)使用的 Sails 就是你link的那個(gè)本地版本$ sails lift這樣你就可以在真實(shí)應(yīng)用場(chǎng)景下驗(yàn)證 fork 中的改動(dòng)確認(rèn)無(wú)誤后再走正式的 PR 流程。需要注意的是sudo取決于你的 npm 全局目錄權(quán)限如果 npm 全局前綴屬于當(dāng)前用戶(hù)通?？梢允÷詓udo。測(cè)試完成后若想恢復(fù)官方版本在應(yīng)用目錄執(zhí)行npm unlink sails并重新npm install即可。八、常見(jiàn)問(wèn)題與最佳實(shí)踐小結(jié)回顧整個(gè)流程給初次貢獻(xiàn)者幾條可操作的建議先溝通再動(dòng)手新特性務(wù)必基于 ROADMAP.md 并先與維護(hù)者對(duì)齊不確定是否算補(bǔ)丁時(shí)先提 issue。保持 PR 小而聚焦單一目標(biāo)、最少改動(dòng)能顯著提高合入概率。測(cè)試與代碼同行bug 修復(fù)盡量配測(cè)試Mocha提交前跑npm test還要留意 package.json 中的lint腳本ESLint--max-warnings0保持代碼風(fēng)格干凈。隨時(shí)同步上游開(kāi)發(fā)前git fetch core git merge core/master減少?zèng)_突。用 npm link 做真實(shí)驗(yàn)證在真實(shí)應(yīng)用里跑通你的 fork再提交 PR避免“看起來(lái)沒(méi)問(wèn)題、跑起來(lái)有問(wèn)題”。Sails 作為一款以 MVC 約定驅(qū)動(dòng)、基于 Express 與 Socket.io 的實(shí)時(shí)框架其核心質(zhì)量正是依靠這樣一套“補(bǔ)丁/特性分流 測(cè)試兜底 窄聚焦 PR”的貢獻(xiàn)機(jī)制來(lái)守護(hù)的。遵循本指南提交你的第一個(gè) PR你就在參與維護(hù)這個(gè)框架的健壯性與可靠性。更多相關(guān)閱讀代碼提交規(guī)范、編寫(xiě)測(cè)試、測(cè)試套件總覽?！久赓M(fèi)下載鏈接】sailsRealtime MVC Framework for Node.js項(xiàng)目地址: https://gitcode.com/gh_mirrors/sa/sails創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考