相比传统的邮件列表 / bugzilla/sourceforge 等开源平台, github 把开源社区交流的成本 / 门槛降的很低, 因此交流的质量也常常随之下降.

我计划写几篇文章, 从 用户 (User) 和 维护者 (Maintainer) 两者的角度写写开源社区中如何使用 issue/PR 进行沟通, 希望能够:

• 让普通用户学会提问, 学会以 maintainer 更容易接受的方式使用 issue/PR 做贡献.
• 给 maintainer 提供一些管理 issue/PR 的经验, 不要再为 issue 头疼.

作为主要开发者和维护者, 我曾经管理过 detectron2 和 tensorpack 等项目.2016-2021 年里我一个人处理过这两个项目里约 5000 个 issue/PR，作为用户, 我也参与了 PyTorch / TensorFlow 等不少项目的社区讨论. 在这个过程中, 看到了开源项目中各种不同的沟通, 管理方式. 现在我已经基本离开了这些项目, 于是想把这些经验总结一下.

这篇文章作为第一篇, 只讨论一些基本的原则.

理解用户和维护者的 Common Interest

在一个项目中, maintainer 和用户的目的常常并不是完全一致的. 有效交流的基础, 是要理解对方与自己 Priority 上的相同和不同.

大多数开源项目的资源都很有限, 用爱发电. 因此, maintainer 自己决定自己的义务 有哪些.

通常, maintainer 不以满足某个用户为目标, 不当 "客服". 这是因为, 相比于其他可以做的事情而言, 给网上的路人提供个人化的 support 对一个项目能够带来的贡献是非常非常小的. 相反, maintainer 通过做其他事情 (例如修 bug) 让项目发展得更好, 来 间接 的帮助所有用户. 通常来说, maintainer 的 priority 是围绕 项目 为中心, 而不是特定用户.

但是, 用户的诉求很多时候就是要解决自己的问题. 这时候用户一定要认识到: maintainer 对解决你的问题并不一定有兴趣.maintainer 愿意与用户交流, 本质是因为用户的 feedbacks 可能让项目变得更好.

让项目变得更好 是用户与 maintainer 的 common interest, 基于这一点的交流才是最有效的, 二者才能有效合作.

有效的交流基于 "Contribution"

让项目变得更好, 换句话说就是 "make contribution to the project".

"Contribution" 这个词在 github 上主要出现于 "contribution calendar", 这是一个记录用户每天的 "contribution activity" 的日历:

在 contribution calendar 上, 不仅与代码相关的行为 (commits, PR, reviews) 算作 "contributions", 有些奇怪的是, 创建 issue 也算作 "contributions". 这可能正是因为, 在 github 设计者的眼里, issue 理应是为了让项目变得更好, 而不仅是解决自己的需求.

用户如果能够理解这一点, 将自己的个人需求转化为对项目的 contribution, 才能把交流变得更有效. 概括来说的话:

• 当用户报告一个问题 (problem, 不是 question) 的时候, 要能够将它描述成 这个项目的问题, 而不仅是 "某个用户的问题".
• 当用户 request feature 的时候, 要 justify 这个 feature 对项目的价值, 而不仅是对自己的价值.
• 当用户提交 patch 的时候, 要 justify 这个 patch 对项目的长期价值 (设计合理, 代码美观, 可维护性, 单元测试等等), 而不仅仅是它是否解决了自己的短期需求.

以上三点在实践中意味着什么, 应该怎么做, 会在后面几篇中再说明.

开源社区 vs. 公司内的交流

开源社区的交流和公司同事间的开发交流在很多方面是相似的, 开源社区中 Maintainer/User 的关系, 也与公司内部 Code Owner/User 的关系类似. 但是, 开源社区里的沟通难度一般会更大:

• 交流效率: 开源社区的交流以原始的 email/forum 形式为主, 而不是即时消息和视频会议. 由于延迟更高, 就要在每条消息中传达尽量多的有用信息.
• 缺少信任: 用户不一定了解维护者, 维护者通常不了解用户, 互相都没有什么 obligations. 缺少信任就不愿意投入时间合作.
• 没有共同的 context: 公司同事间, 大家用一样的 terminology, 一样的开发环境等等, 免去了很多交流障碍.
• Common Interest: 公司内部有更多的 Common Interest, "用户的问题" 和 "项目的问题" 最终都是 "公司的问题". 因此, 开发一个项目的 Code Owner 常常是有明确的义务去解决公司内用户的问题的. 然而, 如上所说, 在开源社区中不是这样.

因此, 开源社区中的交流方式, 对公司内的交流有参考意义, 但不一定完全适用. 例如下一篇"如何报bug"就更通用.

人类语言的模糊性

人类语言是模糊, 容易歧义的, 上面提到的开源社区中交流的障碍, 会把人类语言的歧义放大.

为了能够在消息中传达更多的有用信息, 在交流中要意识到人类语言的局限性. 交流中的每一方如果可以花少量额外时间, 使用代码, 复制粘贴等方式, 将信息尽量组织的更客观, 消除歧义, 就会使交流更有效. 毕竟交流的延迟很大 (至少以小时为单位), 如果更精确的表述能够为双方节省一次 round trip, 就已经赚了.

例如, 在开源社区的交流中:

• 不要说 "我在 A 函数里做了 B", 复制粘贴代码更准确
  • 到底怎么样 "在 A 函数里加入 B", 每个人的理解可能不一样
• 不要说 "我的 libA 的版本是 X", 要提供检查版本的代码 / 命令及其输出
  • 怎么确认版本, 可能有多种方法
• 不要用 "我在 xx 模式运行程序" 来代替 ./main --mode=xx. 后者更准确
• 不要用语言描述来代替可以复制粘贴的 log. 后者更准确
• 报 bug 时, 如果尝试了方案 X 没用, 不要说 "It still doesn't work after X". 因为这是模糊的人类语言, 没有区分下面两种情况:
  • 如果程序的输出和之前相同, 那就说 "输出和之前完全相同"
  • 如果程序的行为有任何变化, 那么应复制粘贴新的 log
• 代词常常自带歧义, 应注意或减少代词的使用.
  • 这篇文章中有个例子:"I started FooApp. It put up a warning window. I tried to close it and it crashed." 这句话里每个 "it" 到底指什么?

类似的例子还有很多. 尽量使用更准确的语言来交流技术问题是个重要的好习惯.