Merge requests workflow · Gitlab 中文文檔

# Merge requests workflow > 原文：[https://docs.gitlab.com/ee/development/contributing/merge_request_workflow.html](https://docs.gitlab.com/ee/development/contributing/merge_request_workflow.html) * [Merge request guidelines](#merge-request-guidelines) * [Keep it simple](#keep-it-simple) * [Commit messages guidelines](#commit-messages-guidelines) * [Contribution acceptance criteria](#contribution-acceptance-criteria) * [Definition of done](#definition-of-done) * [Dependencies](#dependencies) * [Incremental improvements](#incremental-improvements) # Merge requests workflow[](#merge-requests-workflow "Permalink") We welcome merge requests from everyone, with fixes and improvements to GitLab code, tests, and documentation. The issues that are specifically suitable for community contributions are listed with the [`Accepting merge requests`](issue_workflow.html#label-for-community-contributors) label, but you are free to contribute to any issue you want. 請注意，如果在任何時候都為當前里程碑標記了一個問題，即使您正在處理它，則 GitLab Inc.團隊成員可能會接管合并請求，以確保工作在發布日期之前完成. 如果要添加未標記的新功能，最好首先創建一個問題（如果還沒有一個問題）并發表評論，要求將其標記為" `Accepting Merge Requests` . 如果還可以更改用戶界面，請提供建議功能的屏幕截圖或線框. 合并請求應提交到 GitLab.com 上的相應項目，例如[GitLab](https://gitlab.com/gitlab-org/gitlab/-/merge_requests) ， [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests) ， [Omnibus GitLab](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests)等. 如果您不熟悉 GitLab 開發（或一般而言的 Web 開發），請參閱" [如何做出貢獻"](index.html#how-to-contribute)部分，以開始解決一些潛在的簡單問題. 要開始開發 GitLab，請下載[GitLab 開發套件，](https://gitlab.com/gitlab-org/gitlab-development-kit)并參閱" [開發"部分](../../README.html)以獲取所需指南. ## Merge request guidelines[](#merge-request-guidelines "Permalink") 如果發現問題，請提交包含修復或改進的合并請求（如果可以），并包括測試. 如果您不知道如何解決該問題，但是可以編寫暴露該問題的測試，我們也將接受. 通常，包含回歸測試的錯誤修復將快速合并，而沒有適當測試的新功能可能會更慢地接收反饋. 進行合并請求的工作流程如下： 1. [叉](../../user/project/repository/forking_workflow.html)項目插入 GitLab.com 您的個人命名空間（或一組）. 2. 在 fork 中創建一個功能分支（不要使用`master` ）. 3. 編寫[測試](../rake_tasks.html#run-tests)和代碼. 4. [Generate a changelog entry with `bin/changelog`](../changelog.html) 5. 如果要編寫文檔，請確保遵循[文檔準則](../documentation/index.html) . 6. 遵循[提交消息準則](#commit-messages-guidelines) . 7. 如果您有多個提交，請通過[壓縮它們](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History#_squashing)將它們組合為幾個邏輯組織的提交，但是如果您正在共享分支上，則不要更改提交歷史記錄. 8. 將提交推送到 fork 中的工作分支. 9. 向主 GitLab 項目中的`master`分支提交合并請求（MR）. 1. 您的合并請求至少需要 1 個批準，但是根據您的更改，您可能需要其他批準. 請參閱[批準準則](../code_review.html#approval-guidelines) . 2. 您不必選擇任何特定的批準人，但是如果您確實希望特定的人批準您的合并請求，則可以選擇. 10. MR 標題應描述您要進行的更改. 11. MR 說明應說明您進行更改的原因. 1. 如果您要提供代碼，請根據"描述"字段中已經提供的默認模板填寫描述. 2. 如果您要提供文檔，請從"選擇模板"菜單中選擇" `Documentation` "，然后根據模板填寫說明. 3. 提及合并請求解決的問題，合并請求合并后，使用" `Solves #XXX`或" `Closes #XXX`語法[自動關閉](../../user/project/issues/managing_issues.html#closing-issues-automatically)問題. 12. 如果允許，請設置相關的里程碑和[標簽](issue_workflow.html) . 13. UI 更改應使用 GitLab 設計系統" [睡衣"中的](https://design.gitlab.com/)可用組件. MR 必須包含" *之前*和*之后"*屏幕截圖. 14. 如果 MR 更改了 CSS 類，請包括受影響頁面的列表，可以通過運行`grep css-class ./app -R`來找到. 15. 如果您的 MR 觸摸了執行 Shell 命令，讀取或打開文件或處理磁盤上文件路徑的代碼，請確保它符合[Shell 命令準則](../shell_commands.html) 16. 如果您的代碼在磁盤上創建了新文件，請閱讀[共享文件準則](../shared_files.html) . 17. 如果您的合并請求添加了一個或多個遷移，請確保在審閱 MR 之前對新數據庫執行所有遷移. 如果檢查導致 MR 發生較大變化，請在檢查完成后再次執行遷移. 18. 為更復雜的遷移編寫測試. 19. 合并請求**必須**遵守[合并請求性能準則](../merge_request_performance_guidelines.html) . 20. 對于使用 Capybara 的測試，請閱讀[如何編寫可靠的異步集成測試](https://thoughtbot.com/blog/write-reliable-asynchronous-integration-tests-with-capybara) . 21. 如果從源安裝 GitLab 時，合并請求中引入的更改需要其他步驟， `doc/install/installation.md`在同一合并請求中將它們添加到`doc/install/installation.md`中. 22. 如果您的合并請求引入了從源代碼升級 GitLab 時需要其他步驟的更改，請在同一合并請求中將它們添加到`doc/update/upgrading_from_source.md`中. 如果這些說明是特定于版本的，請將它們添加到"特定于版本的升級說明"部分. 23. 閱讀并遵守[合并請求作者的責任](../code_review.html#the-responsibility-of-the-merge-request-author) . 24. 閱讀并關注[審核您的合并請求](../code_review.html#having-your-merge-request-reviewed) . 如果您想對合并請求提供快速反饋，請隨時提及[核心團隊](https://about.gitlab.com/community/core-team/)或[合并請求指導者之一](https://about.gitlab.com/company/team/) . 在審查您的代碼以及審查合并請求時，請牢記[代碼審查準則](../code_review.html) . 并且，如果您的代碼也對數據庫進行了更改或進行了昂貴的查詢，請查看[數據庫復審指南](../database_review.html) . ### Keep it simple[](#keep-it-simple "Permalink") *進行較小的迭代.* 請保持單個 MR 中的更改量**盡可能小** . 如果您想提供較大的功能，請仔細考慮[最小的可行更改](https://about.gitlab.com/handbook/product/#the-minimally-viable-change) . 您可以將功能分為兩個較小的 MR 嗎？您只能提交后端/ API 代碼嗎？您可以從一個非常簡單的 UI 開始嗎？您可以只做一部分重構嗎？小型 MR 更易于查看，從而導致更高的代碼質量，對于 GitLab 而言，這比具有最少的提交日志更為重要. MR 越小，合并的可能性就越大. 之后，您可以發送更多 MR，以增強和擴展功能. Kubernetes 團隊的《 [如何獲得更快的 PR 評論》](https://github.com/kubernetes/kubernetes/blob/release-1.5/docs/devel/faster_reviews.md)文檔也對此有一些建議. ### Commit messages guidelines[](#commit-messages-guidelines "Permalink") 編寫提交消息時，請遵循以下準則： * 提交主題必須包含至少 3 個字. * 提交主題不得超過 72 個字符. * 提交主題必須以大寫字母開頭. * 提交主題不得以句號結尾. * 提交主題和正文必須用空白行分隔. * 提交正文每行不得包含超過 72 個字符. * 在至少 3 個文件中更改 30 行或更多行的提交必須在提交正文中描述這些更改. * 提交主題或正文不得包含表情符號. * 使用問題并合并請求的完整 URL 而不是簡短參考，因為它們在 GitLab 之外顯示為純文本. * 合并請求不得包含超過 10 條提交消息. 如果不符合指導原則，MR 將不會通過[危險檢查](https://gitlab.com/gitlab-org/gitlab/blob/master/danger/commit_messages/Dangerfile) . 有關更多信息，請參見[如何編寫 Git 提交消息](https://chris.beams.io/posts/git-commit/) . 可以在您的計算機上使用的體現以上內容的示例提交消息模板（有關[如何應用 template 的](https://codeinthehole.com/tips/a-useful-template-for-commit-messages/)指南）： ``` # (If applied, this commit will...) <subject> (Max 50 char) # |<---- Using a Maximum Of 50 Characters ---->| # Explain why this change is being made # |<---- Try To Limit Each Line to a Maximum Of 72 Characters ---->| # Provide links or keys to any relevant tickets, articles or other resources # Use issues and merge requests' full URLs instead of short references, # as they are displayed as plain text outside of GitLab # --- COMMIT END --- # -------------------- # Remember to # Capitalize the subject line # Use the imperative mood in the subject line # Do not end the subject line with a period # Subject must contain at least 3 words # Separate subject from body with a blank line # Commits that change 30 or more lines across at least 3 files must # describe these changes in the commit body # Do not use Emojis # Use the body to explain what and why vs. how # Can use multiple lines with "-" for bullet points in body # For more information: https://chris.beams.io/posts/git-commit/ # -------------------- ``` ## Contribution acceptance criteria[](#contribution-acceptance-criteria "Permalink") 為確保您的合并請求能夠獲得批準，請確保其符合以下捐款接受標準： 1. 更改盡可能小. 2. 包括適當的測試并使所有測試通過（除非它包含暴露現有代碼中的錯誤的測試）. 每個新類都應具有相應的單元測試，即使該類是在較高級別上進行的，例如功能測試. * 如果失敗的 CI 構建似乎與您的貢獻無關，則可以嘗試重新啟動失敗的 CI 作業，從主服務器重新部署以引入可以解決該失敗的更新，或者如果尚未解決，請請開發人員來幫助您修復測試. 3. MR 最初包含一些按邏輯組織的提交. 4. 更改可以合并而不會出現問題. 否則，如果您是功能分支上的唯一成員，則應重新設置基準，否則合并`master` . 5. 僅解決了一個特定問題或實現了一個特定功能. 不要結合東西；針對每個問題或功能發送單獨的合并請求. 6. 遷移應僅做一件事（例如，創建表，將數據移動到新表或刪除舊表），以幫助重試失敗. 7. 包含其他用戶將從中受益的功能. 8. 不要添加配置選項或設置選項，因為它們會使進行和測試將來的更改復雜化. 9. 更改不會降低性能： * 避免重復輪詢需要大量開銷的端點. * 通過 SQL 日志或[`QueryRecorder`](../merge_request_performance_guidelines.html)檢查 N + 1 個查詢. * 避免重復訪問文件系統. * 如果需要支持實時功能，可將[輪詢與 ETag 緩存一起](../polling.html)使用. 10. 如果合并請求添加了任何新庫（寶石，JavaScript 庫等），則它們應符合我們的[許可準則](../licensing.html) . 如果" license-finder"測試失敗，并且`Dependencies that need approval`錯誤`Dependencies that need approval`請參閱那些說明. 另外，使審閱者了解新庫并解釋為什么需要它. 11. 合并請求符合下面的 GitLab [對 done](#definition-of-done)的[定義](#definition-of-done) . ## Definition of done[](#definition-of-done "Permalink") 如果您為 GitLab 做貢獻，請知道更改不僅涉及代碼. 我們使用以下[完成的定義](https://www.agilealliance.org/glossary/definition-of-done) . 在您確定滿足所有這些要求之前，您的貢獻不會*完成* . 1. 清晰的說明，說明捐款的相關性. 2. 工作并清理需要注釋的代碼. 3. 所有通過 CI 服務器的[單元測試，集成測試和系統測試](../testing_guide/index.html) . 4. 測試涵蓋了回歸和錯誤，可降低問題再次發生的風險. 5. 遵循[性能準則](../merge_request_performance_guidelines.html) . 6. 遵循[安全編碼準則](https://gitlab.com/gitlab-com/gl-security/security-guidelines) . 7. [記錄](../documentation/index.html)在`/doc`目錄中. 8. 如有必要， [添加了 Changelog 條目](../changelog.html) . 9. 由相關（UX / FE / BE /技術寫作）審稿人審閱，并解決所有問題. 10. 由項目維護者合并. 11. 在[基礎結構問題跟蹤器中](https://gitlab.com/gitlab-com/gl-infra/infrastructure/-/issues)創建問題，以在您的文稿更改默認設置或引入新設置（如果相關）時通知基礎結構部門. 12. 部署貢獻后，確認已在[Canary 階段](https://about.gitlab.com/handbook/engineering/#canary-testing)或 GitLab.com 上工作. 13. 添加到[發布中](https://about.gitlab.com/handbook/marketing/blog/release-posts/) （如果相關）. 14. 添加到[網站](https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/data/features.yml) （如果相關）. 15. 如果需要， [可以](../testing_guide/testing_levels.html#black-box-tests-at-the-system-level-aka-end-to-end-tests)添加[黑盒測試/端到端測試](../testing_guide/testing_levels.html#black-box-tests-at-the-system-level-aka-end-to-end-tests) . 如有任何疑問，請聯系[質量團隊](https://about.gitlab.com/handbook/engineering/quality/#teams) . ## Dependencies[](#dependencies "Permalink") 如果您在 GitLab 中添加了一個依賴項（例如操作系統軟件包），請考慮更新以下內容，并在合并請求中注意每個依賴項的適用性： 1. 請注意[發布博客文章中](https://about.gitlab.com/handbook/marketing/blog/release-posts/)的附加內容（如果尚不存在，請創建一個）. 2. [The upgrade guide](../../update/upgrading_from_source.html). 3. The [GitLab Installation Guide](../../install/installation.html#1-packages-and-dependencies). 4. The [GitLab Development Kit](https://gitlab.com/gitlab-org/gitlab-development-kit). 5. The [CI environment preparation](https://gitlab.com/gitlab-org/gitlab/blob/master/scripts/prepare_build.sh). 6. The [Omnibus package creator](https://gitlab.com/gitlab-org/omnibus-gitlab). ## Incremental improvements[](#incremental-improvements "Permalink") 我們會在工程上花費一些時間來解決小問題（有或沒有問題），這些小問題是逐步改進的，例如： 1. 未經優先考慮的錯誤修復（例如[，到處都顯示有關項目移動的橫幅警報](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/18985) ） 2. 文檔改進 3. Rubocop 或代碼質量改進用?"應該工作的東西"標記合并請求，以跟蹤該區域中的工作.