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