Help us learn about your current experience with the documentation. Take the survey.

合并请求工作流

我们欢迎来自所有人的合并请求，内容是对 GitLab 代码、测试和文档的修复与改进。特别适合社区贡献的问题会带有 Seeking community contributions 标签，但您可以自由地为您感兴趣的任何问题贡献代码。

从问题入手

如果您发现一个问题，请尽可能提交一个包含修复或改进的合并请求，并附上测试。

如果您想添加一个未被标记的新功能，最好先创建一个问题（如果尚不存在），并留下一条评论，请求将其标记为 Seeking community contributions。请参阅 功能提案 部分。

如果您不知道如何修复该问题，但可以编写一个暴露该问题的测试，我们也会接受。通常，包含回归测试的缺陷修复会被快速合并。没有适当测试的新功能可能需要更长时间才能获得反馈。

如果您是 GitLab 开发（或一般的 Web 开发）新手，请参阅 如何贡献 部分，从一些可能比较简单的问题入手。

合并请求的所有权

如果一个问题在任何时候被标记为当前里程碑的一部分，即使您正在处理它，GitLab 团队成员也可能接管该合并请求，以确保在发布日期前完成工作。

如果贡献者不再积极处理已提交的合并请求，我们可以：

  • 决定由我们其中一位 合并请求教练 来完成该合并请求。
  • 关闭该合并请求。

我们根据该变更对产品愿景的重要性来做出此决定。如果将由合并请求教练来完成合并请求，我们会分配 ~coach will finish 标签。

当团队成员接手社区贡献时，我们会通过添加一条更新日志条目来归功于原作者，并可选地将原作者包含在 MR 中的至少一个提交中。

贡献者的合并请求指南

有关贡献过程的演练，请参阅 教程：进行 GitLab 贡献。

最佳实践

  • 如果变更非同小可，我们鼓励您与 产品经理或团队成员 进行讨论。您可以在提交代码以供审查之前，在 MR 中提及他们。在设计决策时，与团队成员交流会很有帮助。传达您更改背后的意图也有助于加快合并请求的审查速度。

  • 如果您认为变更可能会影响生产环境的可用性，请考虑将您的代码置于功能开关之后。不确定？请阅读 何时使用功能开关。

  • 如果您希望对合并请求获得快速反馈，请随时提及 核心团队 或 合并请求教练 中的某位成员。在审查代码和审查合并请求时，请牢记 代码审查指南。此外，如果您的代码还对数据库进行了更改或执行了高开销的查询，请查阅 数据库审查指南。

保持简单

遵循小迭代的原则。 保持单个 MR 中的变更量 尽可能小。 如果您想贡献一个大型功能，请非常仔细地思考什么是 最小有价值变更。您能否将该功能拆分为两个较小的 MR？您能否只提交后端/API 代码？您能否从一个非常简单的 UI 开始？您能否只进行重构的一部分？

更易于审查的小型 MR 能带来更高的代码质量，这对 GitLab 而言比拥有最简的提交日志更为重要。MR 越小，就越有可能被快速合并。之后，您可以发送更多的 MR 来增强和扩展该功能。Kubernetes 团队的 如何获得更快的 PR 审查 文档也对此有一些很好的观点。

提交信息指南

提交信息应遵循以下指南，原因由 Chris Beams 在 如何编写 Git 提交信息 中解释：

  • 提交主题和正文必须用一个空行隔开。
  • 提交主题必须以大写字母开头。
  • 提交主题长度不得超过 72 个字符。
  • 提交主题不得以句号结尾。
  • 提交正文的每行不得超过 72 个字符。
  • 提交主题或正文中不得包含表情符号。
  • 如果一个提交更改了至少 3 个文件中的 30 行或更多代码，则应在提交正文中描述这些更改。
  • 使用问题、里程碑和合并请求的完整 URL，而不是简短引用，因为它们在 GitLab 之外显示为纯文本。
  • 合并请求不应包含超过 10 条提交信息。
  • 提交主题应至少包含 3 个单词。

重要提示：

  • 如果未满足这些指南，MR 可能无法通过 Danger 检查。
  • 如果您的合并请求包含“已对 X 个文件应用建议”之类的提交，请考虑启用 压缩并合并，以便 Danger 可以忽略这些提交。
  • 允许使用 [prefix] 或 prefix: 形式的前缀（只要消息本身首字母大写，前缀可以全部小写）。例如，danger: Improve Danger behavior 和 [API] Improve the labels endpoint 是有效的提交信息。

为什么这些标准很重要

  1. 遵循这些指南的一致性提交信息使历史记录更易于阅读。
  2. 简洁的标准提交信息有助于在审查两个时间点之间的提交时，更快地识别出部署或 ~“master:broken” 的 重大变更。

提交信息模板

可以在您的机器上使用的提交信息模板示例，它体现了上述原则（如何应用模板指南）：

# (If applied, this commit will...) <subject>        (Max 72 characters)
# |<----          Using a Maximum Of 72 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 should
#    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://cbea.ms/git-commit/
# --------------------

贡献接受标准

为确保您的合并请求可以被批准，请确保它满足以下贡献接受标准：

  1. 变更尽可能小。
  2. 如果合并请求包含超过 500 处更改：
    • 解释原因
    • 提及一位维护者
  3. 提及任何重大的 重大变更。
  4. 包含适当的测试并确保所有测试通过（除非它包含一个暴露现有代码中 bug 的测试）。每个新类都应有相应的单元测试，即使该类在更高级别（如功能测试）中被测试。
    • 如果失败的 CI 构建似乎与您的贡献无关，您可以尝试重新运行失败的 CI 作业，在目标分支上进行变基以引入可能解决该问题的更新，或者如果问题尚未修复，请请求开发者帮助您修复测试。
  5. MR 包含少量逻辑上组织良好的提交，或已启用 压缩提交。
  6. 变更可以无问题地合并。如果不能，如果您是唯一在功能分支上工作的人，您应该进行变基；否则，将默认分支合并到 MR 分支中。
  7. 只修复一个特定的问题或实现一个特定的功能。不要将多个事项合并在一起；为每个问题或功能发送单独的合并请求。
  8. 数据库迁移应只做一件事（例如，创建表、将数据移动到新表或删除旧表），以便在失败时重试。
  9. 包含其他用户将从中受益的功能。
  10. 不添加配置选项或设置选项，因为它们会使未来的变更和测试变得复杂。
  11. 变更不会降低性能：
    • 避免轮询需要大量开销的端点。
    • 通过 SQL 日志或 QueryRecorder 检查 N+1 查询。
    • 避免重复访问文件系统。
    • 如果需要支持实时功能，请使用 带有 ETag 缓存的轮询。
  12. 如果合并请求添加了任何新库（如 gems 或 JavaScript 库），它们应符合我们的 许可指南。如果 “license-finder” 测试因 需要批准的依赖项 错误而失败，请参阅这些说明以获取帮助。同时，让审查者知道新库，并解释您为什么需要它。
  13. 合并请求满足下述 GitLab 完成定义。

完成定义

如果您为 GitLab 做出贡献，请知道变更不仅仅是代码。我们使用以下 完成定义。要达到完成定义，合并请求必须不产生回归，并满足所有以下标准：

如果发生回归，我们希望您回滚该更改。在确保您的贡献满足所有这些要求之前，它是不完整的。

功能性

  1. 代码可用且干净，在需要的地方有注释。

  2. 已评估该变更以 限制影响深远的工作。

  3. 遵循了 性能指南。

  4. 遵循了 安全编码指南。

  5. 遵循了 应用和速率限制指南。

  6. 已在 /doc 目录中 记录。

  7. 如果您的 MR 涉及执行 shell 命令、读取或打开文件或处理磁盘上文件路径的代码，请确保它遵循 shell 命令指南。

  8. 代码更改应包含可观测性工具。

  9. 如果您的代码需要处理文件存储，请参阅 上传文档。

  10. 如果您的合并请求添加了一个或多个数据库迁移，请确保在审查 MR 之前，在全新的数据库上执行所有迁移。如果审查导致 MR 中发生重大更改，请在审查完成后再次执行迁移。

  11. 如果您的合并请求向现有模型添加了新的验证，为确保数据处理向后兼容：

    • 在 #database Slack 频道中请求帮助，以执行检查现有行的数据库查询，确保现有行不会受到更改的影响。
    • 使用功能标志添加必要的验证，以便根据 推出步骤 逐步推出。

    如果此合并请求紧急，代码所有者应就是否应将审查现有行作为合并请求的立即后续任务做出最终决定。

    我们无法了解客户在其 GitLab 自托管实例 上的任何数据，因此请记住您的合并请求对数据的任何影响。

    1. 考虑自托管功能和升级路径。该变更应同时考虑：
    • 是否需要额外的工作来确保自托管可用性，以及
    • 该变更是否在升级 GitLab 版本时需要 必需的停机。

    当 GitLab 代码更改依赖于后台迁移已经完成时，有时会请求必需的停机。理想情况下，导致必需停机升级的变更应推迟到下一个主要版本，或者 如果不可避免，至少提前 3 个里程碑通知。

测试

  1. 单元、集成和系统测试 在 CI 服务器上全部通过。
  2. 当变更风险很高时，同行成员测试是可选的，但建议进行。这包括当变更是 影响深远的工作 或 对安全至关重要的组件 时。
  3. 回归和缺陷通过测试覆盖，以降低问题再次发生的风险。
  4. 对于使用 Capybara 的测试，请阅读 如何编写可靠的异步集成测试。
  5. 如果需要，添加了 黑盒测试/端到端测试。如有任何问题，请联系 质量团队。
  6. 在可能且合适的情况下，变更在审查应用中进行了测试。
  7. 受功能标志影响的代码，通过 启用和禁用功能标志的自动化测试 进行覆盖，或者两种状态都作为同行成员测试或推出计划的一部分进行了测试。
  8. 如果您的合并请求添加了一个或多个数据库迁移，请为更复杂的迁移编写测试。

UI 更改

  1. 使用 GitLab 设计系统 Pajamas 中可用的组件。
  2. 如果进行了 UI 更改，MR 必须包含“之前”和“之后”的截图。
  3. 如果 MR 更改了 CSS 类，请包含受影响的页面列表，可以通过运行 grep css-class ./app -R 找到这些页面。

更改描述

  1. 清晰的标题和描述，解释贡献的相关性。
  2. 描述中包含任何步骤或设置，以确保审查者可以查看您所做的更改（例如，包含有关功能标志的任何信息）。
  3. 如有必要，已添加更新日志条目。
  4. 如果您的合并请求引入了在自行编译 GitLab 时需要额外步骤的更改，请在同一个合并请求中将它们添加到 doc/install/self_compiled/_index.md。
  5. 如果您的合并请求引入了从源代码升级 GitLab 时需要额外步骤的更改，请在同一个合并请求中将它们添加到 doc/update/upgrading_from_source.md。如果这些说明特定于某个版本，请将它们添加到“特定版本升级说明”部分。

批准

  1. 已根据 MR 接受清单 对 MR 进行了评估。
  2. 如果您的更改是更改默认设置或引入新设置，请在 基础设施问题跟踪器 中创建一个问题，以通知基础设施部门（如果适用）。
  3. 有一个商定的 推出计划。
  4. 已由相关审查者审查，并已解决所有关于可用性、回归和安全的疑虑。文档审查应尽快进行，但不应阻止合并请求。
  5. 您的合并请求至少有 1 个批准，但根据您的更改，您可能需要额外的批准。请参阅 批准指南。
    • 您不必选择任何特定的批准者，但如果您确实希望特定的人批准您的合并请求，也可以选择。
  6. 由项目维护者合并。

生产环境使用

合并请求合并后，将检查以下项目：

  1. 在可能的情况下，在实施更改之前，已在预发布环境中验证可用。
  2. 在贡献部署后，已确认在生产环境中正常工作，且没有新的 Sentry 错误。
  3. 已确认 推出计划 已完成。
  4. 如果变更存在性能风险，您已在变更前后分析了系统的性能。
  5. 如果合并请求使用功能标志、按项目或按组启用以及分阶段推出：
    • 已确认在 GitLab 项目上正常工作。
    • 已确认在为所有添加的项目设置的每个阶段都正常工作。
  6. 如果相关，已添加到 发布文章 中。
  7. 如果相关，已添加到 网站 中。

贡献不需要 产品团队 的批准。

依赖项

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

  1. 在 发布博客文章 中注明添加内容（如果尚不存在，请创建一个）。
  2. 升级指南。
  3. GitLab 安装指南。
  4. GitLab 开发工具包。
  5. CI 环境准备。
  6. Linux 包创建工具。
  7. 云原生 GitLab Dockerfile

增量改进

我们允许工程时间来修复小问题（有或没有对应的问题），这些问题是增量改进，例如：

  1. 未优先处理的缺陷修复（例如，项目移动横幅警报到处显示）
  2. 文档改进
  3. RuboCop 或代码质量改进

为在此领域跟踪工作，请使用 ~“Stuff that should Just Work” 标签标记合并请求。

相关主题