Swift 如何以及何时使用功能分支

何时使用功能分支？

当您有一系列需要最终以一步的方式添加到 master 的长期工作，但完成它需要协作和实验时，就使用功能分支。例如，向 Swift 添加存储策略需要一个功能分支。这是一项巨大的变化，需要社区中许多人的投入，但在我们开始时，最终的设计或更改尚不清楚。功能分支使我们能够一起工作和实验，然后再发现最终合并到 master 的解决方案。

如何创建功能分支

上游功能分支只能由 openstack-infra 团队的成员创建。PTL 应该前往 -infra IRC 频道并要求创建它。PTL 应该请求功能分支的名称以及应该提交的特定 SHA。

功能分支始终以“feature/<name>”的形式命名。例如，Swift 已经使用了“feature/storage_policies”、“feature/ec”、“feature/crypto”和“feature/hummingbird”。在本文档中，我们将使用“feature/foo”。

功能分支的名称在所有 OpenStack 项目中都应该是唯一的。CI 系统会针对同名的分支进行测试，因此为了确保跨项目集成测试仍然有效，功能分支必须在项目之间是唯一的。（但是，如果两个项目正在合作开发单个功能，它们可以使用相同的分支名称来一起测试。）

注意：此过程现在通过 openstack/releases 仓库实现自动化。 http://git.openstack.org/cgit/openstack/releases/tree/README.rst

更新 gerritbot 报告，以便您的 IRC 频道更新此分支上的活动也是一个好主意。更新 `openstack-infra/project-config/gerritbot/channels.yaml` 并将“feature/<name>”和“feature/<name>-review”添加到您的 IRC 频道配置中。“-review”在以后会很有用。请参阅下面有关将功能分支合并到 master 的部分。

功能分支上的生活

功能分支上的生活在很大程度上与 master 分支上的生活相同。我们发现有一些事情很有帮助。

频繁地从 master 合并（只有核心成员可以执行此操作）
允许实验

由于功能分支是长期存在的，因此将 master 的更改合并到功能分支中非常重要。根据 master 和功能分支的开发速度，这应该每隔一两周发生一次，最多。

请记住，功能分支用于实验。一些通常用于合并到 master 的规则可能会放宽（这取决于整个团队）。也许允许合并不完整的补丁。也许补丁在提交之前不需要完整的文档。也许迁移/升级策略在提交补丁之前不需要完全确定。也许您希望仅使用一个 +2 来提交内容。

重要的是，将会有代码提交到功能分支，但永远不会合并到 master。

经验强烈建议至少有一位核心评审人员积极参与功能分支的日常工作。

将功能分支合并到 master

在 feature/foo 上开发的功能完成后并准备好投入使用后，它应该合并到 master。但是，由于 feature/foo 包含实验和令人困惑的历史记录，在向更广泛的社区进行审查之前，应该对其进行清理。

首先，创建一个名为“feature/<name>-review”的新功能分支。以我们上面的示例为例，我们将创建“feature/foo-review”。此 review 分支用于将代码合并到 master。它将是整体的逻辑组件的相对较少的补丁。这样，补丁链的评审人员可以通过理解小部分来轻松理解整体。

指定一个人（核心评审人员）来管理 review 分支上的补丁链。很可能，这将是一位长期参与功能分支的核心评审人员。此人将向 review 分支提出补丁链并收集每天的审查评论。每天，此人应该推送整个补丁链的新版本，修复审查中提出的问题并处理任何必要的 rebase。

经验强烈建议功能文档成为 review 补丁链中的最后一个补丁。

在 feature/foo-review 分支被审查时，PTL 应该对 master 施加软冻结。这有两点作用。首先，它避免了与 feature review 分支不必要的合并冲突。其次，最重要的是，它迫使整个社区专注于该功能，并提供一个截止日期以鼓励人们完成工作。

软冻结和审查工作应该有时间限制。从一到两周开始（最多），具体取决于正在审查的功能范围。到期后，如果 review 分支尚未合并到 master，则重新评估并根据需要延长截止日期。

评审人员应像往常一样审查 review 分支。可能，社区会希望获得超过标准 2 个 +2 才能合并此功能。如果您有一个需要功能分支的足够大的功能，您可能希望超过 2 个核心成员在将其合并到 master 之前批准它。评审人员不应提交（+A）补丁到 review 分支。评审人员不应覆盖 review 分支上的补丁（让协调人员执行此操作）；相反，评审人员应在审查评论中留下差异。

一旦 review 分支上的补丁链获得共识批准，PTL 应该将补丁提交到 review 分支。然后 PTL 应该创建一个没有快进的合并提交到 master。当此合并提交到达 master 时，就完成了。

最重要的事情

在功能分支上开发期间，甚至在功能 review 过程中，社区必须相互沟通。IRC 很棒，但电话会议和面对面的会议非常有帮助，如果可能的话。

总结

feature/foo

在工作开始时上游创建（不要忘记在第一次提交时更新 .gitreview）
编码、审查、重复
功能完成后，转到 foo-review
预计功能开发一开始会很慢，并且随着更多人参与（尤其是在最终审查阶段）会加速

feature/foo-review

在功能分支基本完成后创建（不要忘记在第一次提交时更新 .gitreview）
提出一个包含最终功能的逻辑补丁链。可能多达 20 个，但更接近 5-8 个更合理，也更可能
master 软冻结，大家审查 foo-review 分支
PTL 用 -2 堵住大门，放在第一个补丁上
评审人员添加他们的审查，像往常一样（但没有 +A）
补丁链管理器将每天收集和应用审查意见
评审人员不得覆盖补丁，而应留下差异
当整个补丁链经过彻底审查后（可能需要每个补丁超过 2 个 +2），则取消阻止并将其合并到 foo-review
PTL 然后提出合并补丁（--no-ff）到 master，以一个提交的方式将该功能带到 master。提交消息包含补丁链中每个作者和共同作者的联合。
PTL 将合并补丁合并到 master 并解除 master 软冻结
始终将文档作为 review 分支链中的最后一个补丁

Swift/功能分支

目录