Merge requests workflow

原文：https://docs.gitlab.com/ee/development/contributing/merge_request_workflow.html

Merge requests workflow

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 label, but you are free to contribute to any issue you want.

请注意，如果在任何时候都为当前里程碑标记了一个问题，即使您正在处理它，则 GitLab Inc.团队成员可能会接管合并请求，以确保工作在发布日期之前完成.

如果要添加未标记的新功能，最好首先创建一个问题（如果还没有一个问题）并发表评论，要求将其标记为” Accepting Merge Requests . 如果还可以更改用户界面，请提供建议功能的屏幕截图或线框.

合并请求应提交到 GitLab.com 上的相应项目，例如GitLab ， GitLab Runner ， Omnibus GitLab等.

如果您不熟悉 GitLab 开发（或一般而言的 Web 开发），请参阅” 如何做出贡献”部分，以开始解决一些潜在的简单问题.

要开始开发 GitLab，请下载GitLab 开发套件，并参阅” 开发”部分以获取所需指南.

Merge request guidelines

如果发现问题，请提交包含修复或改进的合并请求（如果可以），并包括测试. 如果您不知道如何解决该问题，但是可以编写暴露该问题的测试，我们也将接受. 通常，包含回归测试的错误修复将快速合并，而没有适当测试的新功能可能会更慢地接收反馈. 进行合并请求的工作流程如下：

  1. 叉项目插入 GitLab.com 您的个人命名空间（或一组）.
  2. 在 fork 中创建一个功能分支（不要使用master ）.
  3. 编写测试和代码.
  4. Generate a changelog entry with bin/changelog
  5. 如果要编写文档，请确保遵循文档准则 .
  6. 遵循提交消息准则 .
  7. 如果您有多个提交，请通过压缩它们将它们组合为几个逻辑组织的提交，但是如果您正在共享分支上，则不要更改提交历史记录.
  8. 将提交推送到 fork 中的工作分支.
  9. 向主 GitLab 项目中的master分支提交合并请求（MR）.
    1. 您的合并请求至少需要 1 个批准，但是根据您的更改，您可能需要其他批准. 请参阅批准准则 .
    2. 您不必选择任何特定的批准人，但是如果您确实希望特定的人批准您的合并请求，则可以选择.
  10. MR 标题应描述您要进行的更改.
  11. MR 说明应说明您进行更改的原因.
    1. 如果您要提供代码，请根据”描述”字段中已经提供的默认模板填写描述.
    2. 如果您要提供文档，请从”选择模板”菜单中选择” Documentation “，然后根据模板填写说明.
    3. 提及合并请求解决的问题，合并请求合并后，使用” Solves #XXX或” Closes #XXX语法自动关闭问题.
  12. 如果允许，请设置相关的里程碑和标签 .
  13. UI 更改应使用 GitLab 设计系统” 睡衣”中的可用组件. MR 必须包含” 之前和之后”屏幕截图.
  14. 如果 MR 更改了 CSS 类，请包括受影响页面的列表，可以通过运行grep css-class ./app -R来找到.
  15. 如果您的 MR 触摸了执行 Shell 命令，读取或打开文件或处理磁盘上文件路径的代码，请确保它符合Shell 命令准则
  16. 如果您的代码在磁盘上创建了新文件，请阅读共享文件准则 .
  17. 如果您的合并请求添加了一个或多个迁移，请确保在审阅 MR 之前对新数据库执行所有迁移. 如果检查导致 MR 发生较大变化，请在检查完成后再次执行迁移.
  18. 为更复杂的迁移编写测试.
  19. 合并请求必须遵守合并请求性能准则 .
  20. 对于使用 Capybara 的测试，请阅读如何编写可靠的异步集成测试 .
  21. 如果从源安装 GitLab 时，合并请求中引入的更改需要其他步骤， doc/install/installation.md在同一合并请求中将它们添加到doc/install/installation.md中.
  22. 如果您的合并请求引入了从源代码升级 GitLab 时需要其他步骤的更改，请在同一合并请求中将它们添加到doc/update/upgrading_from_source.md中. 如果这些说明是特定于版本的，请将它们添加到”特定于版本的升级说明”部分.
  23. 阅读并遵守合并请求作者的责任 .
  24. 阅读并关注审核您的合并请求 .

如果您想对合并请求提供快速反馈，请随时提及核心团队或合并请求指导者之一 . 在审查您的代码以及审查合并请求时，请牢记代码审查准则 . 并且，如果您的代码也对数据库进行了更改或进行了昂贵的查询，请查看数据库复审指南 .

Keep it simple

进行较小的迭代. 请保持单个 MR 中的更改量尽可能小 . 如果您想提供较大的功能，请仔细考虑最小的可行更改 . 您可以将功能分为两个较小的 MR 吗？ 您只能提交后端/ API 代码吗？ 您可以从一个非常简单的 UI 开始吗？ 您可以只做一部分重构吗？

小型 MR 更易于查看，从而导致更高的代码质量，对于 GitLab 而言，这比具有最少的提交日志更为重要. MR 越小，合并的可能性就越大. 之后，您可以发送更多 MR，以增强和扩展功能. Kubernetes 团队的《 如何获得更快的 PR 评论》文档也对此有一些建议.

Commit messages guidelines

编写提交消息时，请遵循以下准则：

  • 提交主题必须包含至少 3 个字.
  • 提交主题不得超过 72 个字符.
  • 提交主题必须以大写字母开头.
  • 提交主题不得以句号结尾.
  • 提交主题和正文必须用空白行分隔.
  • 提交正文每行不得包含超过 72 个字符.
  • 在至少 3 个文件中更改 30 行或更多行的提交必须在提交正文中描述这些更改.
  • 提交主题或正文不得包含表情符号.
  • 使用问题并合并请求的完整 URL 而不是简短参考，因为它们在 GitLab 之外显示为纯文本.
  • 合并请求不得包含超过 10 条提交消息.

如果不符合指导原则，MR 将不会通过危险检查 . 有关更多信息，请参见如何编写 Git 提交消息 .

可以在您的计算机上使用的体现以上内容的示例提交消息模板（有关如何应用 template 的指南）：

  1. # (If applied, this commit will...) <subject> (Max 50 char)
  2. # |<----  Using a Maximum Of 50 Characters  ---->|
  4. # Explain why this change is being made
  5. # |<----   Try To Limit Each Line to a Maximum Of 72 Characters   ---->|
  7. # Provide links or keys to any relevant tickets, articles or other resources
  8. # Use issues and merge requests' full URLs instead of short references,
  9. # as they are displayed as plain text outside of GitLab
  11. # --- COMMIT END ---
  12. # --------------------
  13. # Remember to
  14. #    Capitalize the subject line
  15. #    Use the imperative mood in the subject line
  16. #    Do not end the subject line with a period
  17. #    Subject must contain at least 3 words
  18. #    Separate subject from body with a blank line
  19. #    Commits that change 30 or more lines across at least 3 files must
  20. #    describe these changes in the commit body
  21. #    Do not use Emojis
  22. #    Use the body to explain what and why vs. how
  23. #    Can use multiple lines with "-" for bullet points in body
  24. #    For more information: https://chris.beams.io/posts/git-commit/
  25. # --------------------

Contribution acceptance criteria

为确保您的合并请求能够获得批准，请确保其符合以下捐款接受标准：

  1. 更改尽可能小.
  2. 包括适当的测试并使所有测试通过（除非它包含暴露现有代码中的错误的测试）. 每个新类都应具有相应的单元测试，即使该类是在较高级别上进行的，例如功能测试.
    • 如果失败的 CI 构建似乎与您的贡献无关，则可以尝试重新启动失败的 CI 作业，从主服务器重新部署以引入可以解决该失败的更新，或者如果尚未解决，请请开发人员来帮助您修复测试.
  3. MR 最初包含一些按逻辑组织的提交.
  4. 更改可以合并而不会出现问题. 否则，如果您是功能分支上的唯一成员，则应重新设置基准，否则合并master .
  5. 仅解决了一个特定问题或实现了一个特定功能. 不要结合东西； 针对每个问题或功能发送单独的合并请求.
  6. 迁移应仅做一件事（例如，创建表，将数据移动到新表或删除旧表），以帮助重试失败.
  7. 包含其他用户将从中受益的功能.
  8. 不要添加配置选项或设置选项，因为它们会使进行和测试将来的更改复杂化.
  9. 更改不会降低性能：
    • 避免重复轮询需要大量开销的端点.
    • 通过 SQL 日志或QueryRecorder检查 N + 1 个查询.
    • 避免重复访问文件系统.
    • 如果需要支持实时功能，可将轮询与 ETag 缓存一起使用.
  10. 如果合并请求添加了任何新库（宝石，JavaScript 库等），则它们应符合我们的许可准则 . 如果” license-finder”测试失败，并且Dependencies that need approval错误Dependencies that need approval请参阅那些说明. 另外，使审阅者了解新库并解释为什么需要它.
  11. 合并请求符合下面的 GitLab 对 done的定义 .

Definition of done

如果您为 GitLab 做贡献，请知道更改不仅涉及代码. 我们使用以下完成的定义 . 在您确定满足所有这些要求之前，您的贡献不会完成 .

  1. 清晰的说明，说明捐款的相关性.
  2. 工作并清理需要注释的代码.
  3. 所有通过 CI 服务器的单元测试，集成测试和系统测试 .
  4. 测试涵盖了回归和错误，可降低问题再次发生的风险.
  5. 遵循性能准则 .
  6. 遵循安全编码准则 .
  7. 记录在/doc目录中.
  8. 如有必要， 添加了 Changelog 条目 .
  9. 由相关（UX / FE / BE /技术写作）审稿人审阅，并解决所有问题.
  10. 由项目维护者合并.
  11. 在基础结构问题跟踪器中创建问题，以在您的文稿更改默认设置或引入新设置（如果相关）时通知基础结构部门.
  12. 部署贡献后，确认已在Canary 阶段或 GitLab.com 上工作.
  13. 添加到发布中 （如果相关）.
  14. 添加到网站 （如果相关）.
  15. 如果需要， 可以添加黑盒测试/端到端测试 . 如有任何疑问，请联系质量团队 .

Dependencies

如果您在 GitLab 中添加了一个依赖项（例如操作系统软件包），请考虑更新以下内容，并在合并请求中注意每个依赖项的适用性：

  1. 请注意发布博客文章中的附加内容（如果尚不存在，请创建一个）.
  2. The upgrade guide.
  3. The GitLab Installation Guide.
  4. The GitLab Development Kit.
  5. The CI environment preparation.
  6. The Omnibus package creator.

Incremental improvements

我们会在工程上花费一些时间来解决小问题（有或没有问题），这些小问题是逐步改进的，例如：

  1. 未经优先考虑的错误修复（例如，到处都显示有关项目移动的横幅警报 ）
  2. 文档改进
  3. Rubocop 或代码质量改进

用〜”应该工作的东西”标记合并请求，以跟踪该区域中的工作.