🔗 Squid 合并流程
本文档概述的要求旨在加快代码更改的接受速度，同时减少重写，最大限度地减少冲突，并保持已提交代码的高质量。如果需要更改要求，请在违反它们*之前*进行讨论。除此之外，请使用常识，做您认为符合 Squid 最大利益的事情。
- 在*开始编码之前*，请确保您的未来更改受到欢迎，并与其他开发人员协调您的计划。
- 在实现更改时，请遵循 SquidCodingGuidelines。使用 Git 进行版本控制（请参阅 GitHints）。
- 完成 提交清单。
- 在 GitHub 上提交一个 拉取请求。
- 监控自动化测试失败情况，并与审查者合作以获得足够的投票，根据需要更新您的拉取请求。
- 如有必要，提醒核心开发人员合并您的合格拉取请求（直到合并自动化）。
- 享受您的代码成为官方的一部分！
- 通过处理错误报告和回答相关的开发问题来支持您的更改。
🔗 开始编码之前
在花费时间编码之前，请在 squid-dev 邮件列表中讨论您的计划，以便其他人可以
- 确认提议的功能尚未支持并且受到欢迎，
- 协助您找到添加功能的最佳方法，以及
- 防止重复工作（其他人可能正在处理类似的更改）。
🔗 提交清单
如果您确定某项不适用于您的情况，请跳过它（风险自负）。
- 代码已准备好在 Squid 许可条款下发布和分发。
- 已更新发行说明：doc/release-notes/release-X.sgml。不用担心 HTML 或 TXT 文件，它们由维护者自动构建。只需要更新 SGML 文件。
- 功能赞助商已添加到 SPONSORS.list 文件中。
- 新导入代码的版权声明和许可证已添加到 CREDITS 文件中。
- 开发分支可以与官方主分支合并而没有冲突，并且合并结果只包含提议的新代码/更改。
- git diff –check upstream/master 不会产生任何警告/错误，并以零状态码退出。根据需要调整远程（即“upstream”）以匹配官方存储库（即github.com:squid-cache/squid.git）。
- ./test-builds.sh 成功。如果测试因官方代码中的错误而失败，请提交错误报告或在 squid-dev 上讨论。如果您无法通过这些基本的构建测试，您未来的拉取请求将会卡住！
🔗 拉取请求
所有提交到官方存储库的更改都需要 GitHub 拉取请求（PR）。此要求确保所有官方更改都经过同行评审，并且所有官方分支始终处于工作状态（当然，在我们的测试能够检测到错误的情况下）。它还有助于减少提交噪音和回溯移植的开销。本节记录了 PR 要求。有关 PR 提交的食谱，请参阅 GitHints。
- 在创建拉取请求之前，请完成 提交清单。如果您确实需要提前发布 PR，请在 PR 标题中以“[WIP] “前缀开头（六个字符表示“进行中”），并在 PR 评论中说明为什么您发布了未经检查的 PR。默认情况下，WIP PR 不会被审查，但它们会通过 CI 测试。
- 请使用英语和纯文本格式。
- PR 标题是预期提交消息的第一行。请具体而简洁。不要超过 65 个字符。
- PR 描述是预期的提交消息正文（遵循上述第一行和一个空行）。避免详细说明您的更改（您的更改应该不言自明！）。重点关注您更改代码的*原因*以及您更改代码的预期*影响*。每行不要超过 72 个字符。
- 默认情况下，各个 PR 分支提交将自动进行“squash-merge”。因此，您可以在发布 PR 时在分支中保留中间提交 - 审查者应忽略它们，而是审查它们的累积结果。避免在 GitHub 审查期间进行 squashing。
- 在 GitHub 审查期间，避免将新的 master（或目标分支）更改合并到您的 PR 分支，除非此类更新变得有必要。PR 获得批准后，您的 PR 分支将自动合并到当时的相应目标分支。
- 非您本人提交的 PR 提交应设置正确的作者（通过*git commit –author=…* 或等效命令）。
如果您无法以拉取请求的形式提交您的更改，请找到可以为您这样做的开发人员。
🔗 投票
第一个匹配的规则获胜。提交者会自动获得一票积极投票。
任何开发人员都可以投票。
- 核心开发人员的一票反对将阻止合并，直到问题解决。
- 核心开发人员的两票赞成将接受提交（并优先合并）。
- 任何三票赞成即可接受提交。
- 超过 10 天且没有反对票的提交将被接受。
🔗 例外
在真正特殊的情况下（这些情况应尽快披露和讨论）
- 核心开发人员可以立即提交任何更改。
- 在提交后的 10 天内，核心开发人员可以随时移除任何提交，而无需事先通知或讨论。但仍需在 squid-dev 上发布事后通知（和讨论）。
🔗 核心开发人员
上面提到的核心开发人员是经验丰富的开发人员，他们对整个 Squid 项目和特别是 Squid 代码有长期认真的贡献。他们通常活跃在 squid-dev 上，并经常审查提交。核心开发人员共同对 Squid 项目负责，并可以使用他们的超级能力来解决冲突或防止灾难。
🔗 自动化
合并自动化强制执行的“受信任主分支”原则规定，主分支会自动接收所有受信任的代码更改，且不包含其他任何内容。在这种情况下，受信任的代码更改，根据定义，是一个非空的 git 提交序列，它满足以下要求：
- 该序列是 GitHub 上一个已批准的拉取请求分支（的开始部分），
- 该序列可以与主分支合并而没有冲突，并且
- 该序列中的最后一个提交已通过所有必需的 QA 测试。
目前，PR 分支在合并时会被 squashed。Squashing 大大减少了主分支的噪音，并确保每个主分支提交都是受信任的，因为自动化测试会检查将要提交的（通常是最后的）PR 分支修订版。如果需要，我们可以在特殊情况下找到一种方法来标记受信任的提交，同时合并未 squashed 的分支。
目前，早期 PR 分支修订版的批准会自动扩展到所有未来的分支修订版（直到手动撤回），但这可能会改变，甚至可能在每个 PR 上进行配置。
自动提交到主分支是由一个名为merge bot的程序执行的。只有 merge bot 有权修改主分支。Squid 项目目前使用 Anubis 合并机器人，配置如下：
| 字段 | 描述 | 值 |
|---|---|---|
| github_login | 该机器人使用此 GitHub 用户帐户进行所有 GitHub 通信，包括目标分支更新。此用户需要对存储库具有写入访问权限。 | “squid-anubis” |
| staging_branch | 机器人维护的 git 分支的名称，用于测试 PR 更改，就像它们已合并到其目标分支一样。 | auto |
| necessary_approvals | PR 需要合并的核心开发人员的最少数量。投票数少于此的 PR 不会合并，无论其年龄如何。 | 1 |
| sufficient_approvals | PR 需要快速合并（即，无需等待config::voting_delay_max）的核心开发人员的最少数量。 |
2 |
| voting_delay_min | PR 的最小合并年龄。较年轻的 PR 不会合并，无论投票数如何。PR 年龄字符串应符合 timestring 解析器。 | “2d” |
| voting_delay_max | 投票数少于config::sufficient_approvals的 PR 的最大合并年龄。PR 年龄字符串应符合 timestring 解析器。 |
“10d” |
| staging_checks | 在暂存分支上执行的 CI 测试的预期数量。 | 2 |
| guarded_run | 只有（手动）标记为 M-cleared-for-merge 的 PR 才会被 Anubis 合并。 |
true |