42/C4

42/C4

集体代码构建契约

集体代码构建契约 (C4) 是 github.com Fork + Pull 模型的演进，旨在为自由软件项目提供最优化的协作模型。这是 C4 规范的修订版 2，取代了 RFC 22。

许可

版权所有 (c) 2009-2016 Pieter Hintjens。

本规范是自由软件；您可以根据自由软件基金会发布的 GNU 通用公共许可证的条款重新分发和/或修改它；许可证的第 3 版，或（由您选择）任何更高版本。

分发本规范是希望它会有用，但没有任何担保；甚至没有适销性或特定用途适用性的默示担保。详情请参阅 GNU 通用公共许可证。

您应该已经收到一份 GNU 通用公共许可证的副本以及本程序；如果没有，请参阅 https://gnu.ac.cn/licenses。

摘要

C4 为软件项目的贡献、评估和讨论改进提供了一个标准流程。它为项目定义了特定的技术要求，如代码风格指南、单元测试、git 和类似平台。它还为项目确立了不同的角色，并明确区分了职责。C4 规定了一个用于记录和讨论问题的流程，包括寻求共识、清晰描述、使用“pull request”和系统性评审。

语言

本文档中的关键词“MUST”、“MUST NOT”、“REQUIRED”、“SHALL”、“SHALL NOT”、“SHOULD”、“SHOULD NOT”、“RECOMMENDED”、“MAY”和“OPTIONAL”应按照 RFC 2119 中的描述进行解释。

1. 目标

C4 旨在为开源软件项目提供一个可复用的最优协作模型。它具有以下具体目标：

  1. 通过减少新贡献者的摩擦，并创建一个具有强大正向反馈的分级参与模型，最大化项目社区的规模和多样性；
  2. 通过分离不同的技能集来减轻对关键个人的依赖，从而在任何所需领域拥有更大的能力储备；
  3. 通过增加决策过程的多样性，使项目更快、更准确地发展；
  4. 通过允许安全实验、快速失败和稳定代码的隔离，支持项目版本从实验阶段到稳定阶段的自然生命周期；
  5. 降低项目仓库的内部复杂性，从而使贡献者更容易参与并减少出错的可能性；
  6. 强制实行项目的集体所有权，这增加了对贡献者的经济激励，并降低了被敌对实体劫持的风险。

2. 设计

2.1. 前言

  1. 项目SHALL使用git分布式版本控制系统。
  2. 项目SHALL托管在github.com或同等平台上，此处称为“平台”。
  3. 项目SHALL使用平台的议题追踪器。
  4. 项目SHOULD拥有清晰记录的代码风格指南。
  5. “贡献者”是指希望提供补丁的人，补丁是解决某个明确问题的提交集。
  6. “维护者”是指将补丁合并到项目的人。维护者不是开发者；他们的职责是执行流程。
  7. 贡献者SHALL NOT拥有仓库的提交权限，除非他们也是维护者。
  8. 维护者SHALL拥有仓库的提交权限。
  9. 任何人，不分区别或歧视，SHALL拥有根据本契约条款成为贡献者的平等权利。

2.2. 许可与所有权

  1. 项目SHALL使用类似共享许可（如 MPLv2 或 GPLv3 的变体，包括 GPL、LGPL、AGPL）。
  2. 所有对项目源代码的贡献（“补丁”）SHALL使用与项目相同的许可。
  3. 所有补丁归其作者所有。SHALL NOT有任何版权转让流程。
  4. 每位贡献者SHALL负责在项目贡献者列表中表明身份。

2.3. 补丁要求

  1. 维护者和贡献者MUST拥有平台账号，并SHOULD使用他们的真实姓名或常用别名。
  2. 补丁SHOULD是对一个明确识别并同意的问题的最小且准确的解答。
  3. 如果项目定义了代码风格指南，补丁MUST遵守这些指南。
  4. 补丁MUST遵守下方定义的“公共契约的演进”指南。
  5. 补丁SHALL NOT包含来自其他项目的非平凡代码，除非贡献者是该代码的原始作者。
  6. 补丁MUST在至少主要目标平台上干净编译并通过项目自测试。
  7. 补丁提交信息MUST由一行简短（少于 50 个字符）的文字组成，说明正在解决的问题（“问题：…”），后跟一个空行，然后再是提议的解决方案（“解决方案：…”）。
  8. “正确补丁”是满足上述要求的补丁。

2.4. 开发流程

  1. 项目的变更SHALL遵循准确识别问题并对这些问题应用最小、准确解决方案的模式。
  2. 要请求变更，用户SHOULD在项目平台的议题追踪器上记录一个议题。
  3. 用户或贡献者SHOULD通过描述他们遇到或观察到的问题来撰写议题。
  4. 用户或贡献者SHOULD就其观察的准确性以及解决问题的价值寻求共识。
  5. 用户SHALL NOT记录功能请求、想法、建议或任何未明确记录且不可证明的问题的解决方案。
  6. 因此，项目的发布历史SHALL是一个记录和解决有意义议题的列表。
  7. 要处理议题，贡献者SHALL Fork项目仓库，然后在他们的Fork仓库上工作。
  8. 要提交补丁，贡献者SHALL在平台创建指向项目的 pull request。
  9. 贡献者SHALL NOT直接提交变更到项目。
  10. 如果平台将 pull request 实现为议题，贡献者MAY直接发送 pull request，而无需单独记录议题。
  11. 要讨论补丁，人们MAY在平台的 pull request、提交或其它地方发表评论。
  12. 要接受或拒绝补丁，维护者SHALL使用平台接口。
  13. 维护者SHOULD NOT合并他们自己的补丁，除非在特殊情况下，例如其他维护者长时间（超过 1-2 天）没有响应。
  14. 维护者SHALL NOT对正确补丁进行价值判断。
  15. 维护者SHALL快速合并来自其他贡献者的正确补丁。
  16. 维护者MAY合并来自其他贡献者的不正确补丁，其目标包括 (a) 结束无效讨论，(b) 在历史记录中捕捉不良补丁，(c) 与贡献者互动以提高他们的补丁质量。
  17. 创建议题的用户SHOULD在检查补丁成功后关闭议题。
  18. 对补丁有价值判断的任何贡献者SHOULD通过他们自己的补丁来表达这些判断。
  19. 维护者SHOULD关闭长时间（令人不适）未采取行动而仍处于打开状态的用户议题。

2.5. 分支与发布

  1. 项目SHALL有一个分支（“main”），它始终保存最新的开发中版本，并且SHOULD始终能够构建。
  2. 项目SHALL NOT出于任何原因使用特性分支（topic branches）。个人 Fork MAY使用特性分支。
  3. 要创建稳定版本，维护者应为仓库打标签。稳定版本SHALL始终从仓库的 main 分支发布。

2.6. 公共契约的演进

  1. 所有公共契约（API 或协议）SHALL被文档化。
  2. 所有公共契约SHOULD为可扩展性和实验预留空间。
  3. 修改稳定公共契约的补丁SHOULD不破坏现有应用程序，除非有压倒性的共识认为这样做有价值。
  4. 引入新功能的补丁SHOULD使用新名称（新契约）来引入。
  5. 新契约SHOULD在稳定并被实际用户使用之前被标记为“草案”。
  6. 旧契约SHOULD以系统性的方式被弃用，将其标记为“已弃用”，并根据需要用新契约替代。
  7. 在经过足够长时间后，旧的已弃用契约SHOULD被移除。
  8. 旧名称SHALL NOT被新契约复用。

2.7. 项目管理

  1. 项目创始人SHALL担任管理员，管理项目维护者集合。
  2. 管理员SHALL通过提拔最有效的维护者来确保自身的传承。
  3. 制作正确补丁、清楚理解项目目标和流程的新贡献者SHOULD被邀请成为维护者。
  4. 管理员SHOULD移除长期不活跃或反复未能准确执行此流程的维护者。
  5. 管理员SHOULD屏蔽或禁止那些对项目中的其他人造成压力和痛苦的“不良行为者”（bad actors）。这应该在公开讨论之后进行，并给予所有相关方发言的机会。不良行为者是指那些屡次忽视项目规则和文化、不必要地好辩或怀有敌意、或冒犯他人、并且在他人要求时无法自我纠正其行为的人。

延伸阅读

  • Argyris 的模型 1 和 2 - C4 的目标与 Argyris 的模型 2 一致。

  • 丰田 Kata - 包括改进 Kata（一次解决一个问题）和教练 Kata（帮助他人学习改进 Kata）。

实现