本文转载自：https://github.com/LinuxSuRen/open-source-best-practice

为什么？

为什么要编写这一份《开源最佳实践》呢？

首先，对于首次准备尝试参与开源的人来说，很容易有无从着手的感觉。完事开头难，希望这一份最佳实践可以帮忙更多有意参与开源的人们。不管你是一名普通的研发、还是一名非技术人员，参与开源必将使得你受益匪浅。

国内（中国）已经有 Gitee 发起、众多开源爱好者共同编撰了《开源指北》，还有 GitHub 官方提供的《开源软件指南》，那这一份最佳实践和之有什么区别吗？开源不仅仅是把代码嗮出来就好了，更加重要的是一种协作精神的文化体验，以及具体落地操作。

与之不同的，本最佳实践更多会从落地实践的角度来讲述。

Get started

仔细阅读项目自述文件（README），遵循贡献指南（CONTRIBUTION）中给出的流程。

面对一个新的项目，尤其是在相对不熟悉的领域，有如下的方法可以帮助你提供前期的贡献：

• 文档贡献，这是非常有效的一种了解项目的方式，通常我们可以在阅读文档的过程中，修复一些错别字、标点符号、语法错误、无效链接等等
• good-first-issues，对于希望收到更多贡献的项目而言，会在一些容易上手的 issues 上添加该标签

Issues

常见误区：

• 只有标题，没有内容
• 只有结果、现象，没有提供上下文
  • 问题出现的可能性千千万，没有人能猜到你的环境、操作步骤
• 只有截图，不提供错误、异常、上下文的关键文字
  • 没有文字的话，不便于其他人进行检索

最佳实践：

• 现有的 issues 中没有提到过该问题时再提交新的
• 熟悉语言一定要遵循对应社区期望的规定
• 标题要简洁、规范
• 做好分类，可以通过标签或者标题前缀来分类
  • 常见的标题分类法：Question: xxx, Proposal: xxx, Bug: xxx
• 和 UI 相关的 issues 要给出截图

Pull Request

常见误区：

• 使用单一分支（例如：master）提交变更
• 单个 PR 中包含多个不同的优化、缺陷修复
• 单个 PR 不断新增内容
• 合并自己提交的 PR
• 通过及时聊天工具催促特定的人 review 你的 PR

最佳实践：

• 首次提交 PR 前，浏览已经成功合并过的 PR 评论列表以及格式等
• 如果要修复的问题已经有对应的 issue，请确保没有人提交对应的 PR，然后，请留言说明你的修复计划
• 如果估计你提交的变更比较多，请首先创建 issue，并依据具体情况（难易程度、争议性等）描述你的想法
• 一个 PR 只能包含一类修改
• 每次提交都须要新增一个分支进行
• 避免同一个主题的 PR 反复关闭、新建
  • 避免在同一个 PR 中频繁地提交，这对于 reviewers 来说将会是极大的困扰
  • 如果你的 PR 还没有准备好接受 review，请在标题上添加前缀 WIP: ，直到你自测充分
  • 在根据 reviewers 提出的建议进行修改时，避免使用强制推送 --force，这对于 reviewers 来说将无法轻松地看到你最新的修改部分
  • 尽可能保持你的 commit 记录比较优雅，万一多次 review 后的记录比较多的话，项目 owners 会在合并时决定是否会 squash 你的提交记录
• 尽可能多地给出当前 PR 的详情，包括但不限于：相关 issues、解决的问题、任何方便 review 的上下文
  • 涉及到 UI 的改动，给出修改前后的效果截图
  • 视情况给出你的自测过程
  • 对于可能引起争议的部分，给出你的解释
• 如果你的 PR 超过一周没有得到 review，可以尝试 cc 相关的 team
  • 如果没有相关的 team 可以 cc 的话，可以找最近合并过类似 PR 的人，并说明是由于找不到其他的方式，以及表示抱歉打扰

Review

在 PR 的 review 过程中，通常会涉及到三个角色的人：作者、维护者、其他。

首先，我们要想明白一个问题——为什么要进行 review ？不管 PR 中提交的是代码、文档还是其他类型的文件，进行 review 的都有着非常重要的意义。

• 开源最基本原则的体现，公开、透明
  • 如果连 review 都不做的话，何谈开源？要公开的绝不仅仅是结果，更关键的是要公开过程
  • review 绝对不是审核的意思，任何人都可以是 reviewer，大家都有可以在这个过程中有所收获
• 生命周期
  • PR 不适用于有紧急合并需求的情况
  • 提交完 PR 后，作者首先应该自行检查一遍，如果发现还有问题的话，请标记为“进行中”
    • 我们可以把还没准备好 review 的 PR 的标题加上前缀：WIP:
    • 作者如果对某些代码（文档）不是很确定，可以直接把你的观点以评论的形式表述出来
  • 在 2～7 天内完成 review 并合并
• 礼仪
  • 没有人有义务对你的 PR 进行 review，包括维护者
  • 每一位 reviewer 都对你的 PR 合并提供了帮助，对他们表示感谢
  • 在最佳的 review 周期内，不要去催促任何人对你的 PR 进行 review
  • 如果确实需要请求 review 帮助，请给出说明，并且优先 @ 某个 team，其次才是直接 @ 某个人，并对打扰表示歉意
• 明确你的观点
  • 尽量避免给出模棱两可的评论，作者需要根据你给出的建议来决定是否要进行修改
  • 对于你不是很确定问题，可以这么表述：”我感觉这里可能有问题，给出建议的做法以及理由，并指明该评论不阻碍 PR 的合并“
  • 对于你很确定有问题的部分，给出可以证明你观点的信息或者数据，如果有相关权威资料的话，一并给出链接
    • 例如：PR 中代码注释不规范，给出官方社区的文档链接
• 自动化流程
  • 利用类似于 Lighthouse 的自动化工具来管理 review 流程
  • 合并之前尽可能多地运行自动化测试（单元测试、e2e 测试、压力测试等）
  • 避免人为干预自动化过程
  • 如果 review 完成，但还需要一些人工验证的话，为避免过早自动合并，可以通过评论命令来阻碍
    • 例如：通过评论 /hold 来阻止机器人账号自动合并

社区运营

对于社区（Community）这个词，不同的人有着不同的理解。本文的社区专指：开源社区（Open Source Community）。

在社区运营过程中，有很多好的实践和方法，例如：社交媒体、Meetup、SIG、TOC 等的运营。下面，给出部分组织形式的最佳实践指导。

SIG 运营

确定 SIG 的准入准出制度，根据团队的实际情况来控制 SIG 的数量，运营的质量是首要考虑的。

SIG 的健康发展，离不开公开、透明、多元化等原则，流于形式的、不符合开源精神的 SIG 没有存在的意义。

SIG 会议

• 每次会议都要有会议开始和结束的表述
  • 例如：现在开始我们今天的例会；结束时可以说：“非常感谢各位参加今天的社区例会”等等的
• 热情地欢迎首次参加例会的成员，并鼓励做自我介绍
• 做必要的上下文介绍
  • 不管是拨入会议还是观看回放的人，都有可能是首次参与，缺少上下文会导致他们难以明白相关讨论
  • 如果有文字性的上下文介绍，尽量在会议记录文档中有体现
• 主持人要把控会议时间、节奏
  • 尽量控制在 1 小时内，未讨论完的议题放到下次讨论
  • 在讨论过程中帮助、引导得出结论
• 使用适当的表述方式
  • 避免使用类似于“我们昨天讨论过xxx”的表述，社区成员无法了解到你们讨论的内容
• 确保例会的周期性
  • 通常情况下，每两周一次的例会比较适中
  • 当参与者人数相对较多，而且分布在不同时区的话，结合参与者的意见可以分两个会议
  • 当可以主持会议的人都无法参加，或者其他需要取消例会的情况，尽早地通知社区会议取消
• 会议记录
  • 文字记录，可以使用 Google Document 或者腾讯文档
  • 会议录屏，根据会议参与者使用的语言不同，中文可以选择哔哩哔哩，英文可以选择 YouTube

其他

还有一些其他的比较推荐的习惯、方法：

• 习惯查看邮件
  • 一定要把自己常用的邮箱地址关联到 GitHub 上，这样才能及时收到 issues 和 PR 中的互动信息
• 通过电脑、手机来管理自己的日程
  • 开源社区总会有各种各样的会议，如果没有使用日历的习惯的话，非常容易遗忘重要的事情

其他参考

• Google Engineering Practices Documentation