维护者的最佳实践
维护者的最佳实践
作为开源维护者, 通过记录流程到充分利用社区, 可以让你的生活更轻松
[TOC]
1. 成为一个维护者意味着什么
如果你维护者一个大量用户使用, 你可能已经意识到你现在已经很少去编码, 而会花大量时间去回复issues.
在一个项目的初期, 你会去尝试许多新的点子, 并且根据你想要什么去做决定. 随着你的项目知名度越来越高, 你会发现你更多的时候是为你的使用者和贡献者工作.
维护一个项目需要的不仅仅是编码. 有些任务常常是出乎意料的, 但他们又对一个成长中的项目非常重要. 我们收集了一些方法是你的生活更加轻松, 从记录流程到充分利用社区资源
2. 记录你的流程
把事情记录下来是作为一个维护者能够做的最重要的一件事情
文档不仅可以阐明你自己的事情, 也可以帮助其他人在询问你之前了解你需要或期望的东西.
写文档可以让你更容易的拒绝一些不适合项目的东西. 也可以让其他人更容易参与帮助你的项目. 你永远不可能知道谁在阅读或使用你的项目.
即使你不写出完整的文档, 记录下重点也比什么都不写好很多.
记住及时更新你的文档. 如果你不能一直这样做, 请删除过期的文档或指出已过时, 以便贡献者了解更新.
写下你的项目的愿景
首先写下你的项目的目标. 把它们添加进README中, 或者创建一个名为VISION的单独的文件. 如果有其他需要帮助的部分, 例如项目流程图, 最后也公开这些东西.
拥有一个清晰的, 文档化的愿景可以让你专注, 并且帮助你避免他人的贡献中的’范围蔓延’.
例如, lord发现拥有一个项目愿景帮助他弄清楚哪些需求需要花费时间. 作为一个新的维护者, 他后悔当他接到第一个Slate功能需求的时候没有坚持自己的项目范围.
我摸索了它, 我没有努力的想出一个完整的解决方案. 我希望我曾经说过’我现在没有时间做这件事, 但我会把他加进长期的目标列表中’, 而不是一个半途而废的解决方法. —- @lord
沟通你的期望
写下这些规则是很伤脑筋的. 有时候你可能觉得你在监督别人的行为或者扼杀所有的乐趣.
然而, 编写和执行良好的规则可以增强维护人员的能力. 它们阻止你去做你不想做的事情.
大部分看到你项目的人都不知道你和你的情况. 他们可能假设你得到报酬, 特别是他们经常使用和依赖的东西. 也许在某个时间, 你花费大量的时间在你的项目上, 但是现在你正忙于一份新的工作或者家庭成员.
所有的这一切都很完美! 只要确保其他人知道就行了.
如果维护你的项目是兼职或者纯粹资源的, 要诚实的告知别人你有多少时间. 这与你认为项目需要花费多少时间, 或者其他人想让你花费多少时间是不一样的.
这里有一些值得写下来的规则:
- 如何评估和接受贡献(是否需要测试?问题模板)
- 你接受什么类型的贡献(你是否只希望得到部分的代码帮助)
- 什么时候适合跟进(例如, 你可以期望维护人在7天之内回应, 如果你到那时还没有听到任何消息, 那就自由的去做吧)
- 你在这个项目上会花费多少时间(例如, 我们平均每个星期只花费5个小时在这个项目上)
Jekyll, CocoaPods, 和Homebrew 是几个项目的例子, 它们为维护人员和贡献者提供了基本规则.
保持沟通公开
也不要忘记及时记录你的沟通记录. 不论你再哪里, 都要保持你的项目公开, 如果有人想要私下和你联系讨论某个功能请求或需求支持, 礼貌的将他引导公共的沟通渠道中, 比如邮件列表或issue tracker(问题追踪器)
如果你想要和其他维护者会面, 或者私下做出一些重大决定, 在公开场合发布这些对话, 即使只是发布一些你的笔记.
这样, 任何加入你的社区的人都可以获得和那些已经在那里多年的人相同的信息.
3. 学会说NO
你已经记录下了一些的事情. 理想情况下, 每个人都会阅读你的文档, 但实际上, 你必须提醒其他人, 这些知识是存在的
把一些都写下来, 不论如何, 它将在你需要执行你的规则的时候帮你个性化解决方案.
说’不’并不有趣, 但’我不喜欢你的贡献’不如’你的项目不符合这个项目的标准’.
说’不’适用于许多你会遇到的维护者: 那些不符合范围的特性请求, 有人破坏了讨论, 对其他人做了不必要的工作.
保持对话友好
你要练习说’不’的最重要的地方之一就是你的issue和pull request. 作为一个项目维护者, 你将不可避免地收到你不想接受的建议.
也许这个贡献改变了你项目的范围或不符合你的愿景. 或者这个想法很好, 但是实现很糟糕.
无论什么原因, 都有可能巧妙地处理那些不符合项目标准的贡献.
如果你收到了一个你不想接受的贡献, 你的第一反应可能是忽略或者假装没有看到. 这样做会伤害别人的感情, 甚至会使你所在社区的其他潜在贡献者失去动力.
为大型开源项目提供支持的关键是保持问题的进展. 尽量避免出现问题. 如果你是一个iOS开发者, 你知道提交雷达是多么令人沮丧. 你可能会在两年后听到, 并被告知尝试使用最新版本的iOS —- @KrauseFx
不要因为内疚或想要友善而对你不想要的贡献置之不理. 随着时间的推移, 你没有回复的issues和PRs将使你的项目感到压力和威胁.
最好立即关闭你明确知道你不想接受的贡献. 如果你的项目已经遭受大量积压, @steveklabnik 对于如何有效的分流问题有一些建议.
其次, 忽略贡献会给你的社区带来一个消极的信号. 对一个项目作出贡献是令人生畏的, 特别是如果这是一些人的第一次. 即使你不接受他们的贡献, 之后也要承认他们, 并感谢他们的关心, 这是一个很大的赞扬!
如果你不想接受一个贡献:
- 感谢他们的贡献
- 解释为什么它不符合项目的范围, 并提供明确的改进建议. 如果可以, 尽量亲和一下，但要坚定.
- 如果你有文档, 链接到相关文档. 如果您注意到重复的请求, 请将它们添加到文档中, 以避免自己重复工作
- 关闭请求
你不应该需要超过1-2个句子来回应. 例如, 当celery用户报告与Windows相关的错误时， @berkerpeksag回应：
如果说’不’的想法吓到了你, 你并不孤单. 就像 @jessfraz 说的:
我和几个不同的开源项目, Mesos, Kubernetes, Chrominm谈过, 他们都认为最为维护者, 对于你不想要的不定说’No’是最困难的部分之一.
不要以为不想接受别人的贡献而感觉到内疚. 根据@shykes的说法, ‘No只是暂时的, Yes才是永久的’. 虽然同求别人的热情是一件好事, 但拒绝一个人的贡献和拒绝一个人的支持是不一样的.
最后, 如果一个贡献不够好, 你就没有义务去接受他. 当被人对你的项目作出贡献的时候, 你要表现的友善和积极, 但只接受你真正相信的修改会让你的项目更好. 你练习说’不’的次数越多, 它就变得越容易. 真的!
主动
为了减少不必要的贡献, 你需要解释在你的贡献指南中说明你的项目提交和接受贡献的过程.
如果你收到了太多低质量的贡献, 则需要贡献者提前做一些工作, 例如:
- 填写issue或者PR的模板/清单
- 在PR之前打开一个issue
如果他们不遵循你的规则, 马上关闭这个issue并指向你的文档.
虽然这种方法一开始可能有些不友好, 但积极主动实际上对双方都有好处. 它减少了有人将大量浪费的工作时间投入到你不愿意接受的请求. 而且它会让你的工作量更容易管理.
理想情况下，向他们说明并且在CONTRIBUTING.md文件解释他们将来如何在开始工作之前得到更好的指示 —- @mikemcquaid
有时候, 当你说’不’时, 你的潜在贡献者可能会感到不安或批评你的决定. 如果他们的行为变得敌对, 采取措施缓和局势, 或者甚至把他们从你的社区中移除, 如果他们不愿意建设性地合作.
接受指导
也许你的社区中的一些人会经常提交一些不符合你项目标准的贡献. 反复的拒绝会让双方都很沮丧.
如果你看到一些人对你的项目很热情, 但需要一些磨砺, 你要有耐心. 在每个情况下清楚地解释为什么他们的贡献不符合项目的期望. 试着将它们指向一个更容易或更不明确的任务, 比如标记一个问题为’很好的第一个BUG’, 让他们初次尝试. 如果你有时间, 可以考虑通过他们的第一个贡献来指导他们, 或者在你的社区里找到一个愿意指导他们的人.
4. 利用你的社区
你不必自己做一切. 你项目的社区存在是有原因的! 即使你还没有一个积极的贡献者社区, 如果你有很多的用户, 让他们工作.
分担工作量
如果您正在寻找其他人参与, 首先从四周询问.
当你看到新的贡献者作出重复贡献时, 通过提供更多的责任来认识他们的工作. 如果他们愿意, 记录下他们如何成长为一个领导者.
鼓励他人分享项目的所有权可以很好的减少你自己的工作量, 就像 @lmccart在她的p5.js项目中发现的那样.
我曾说过, ‘是的, 每个人都可以参与, 你不需要拥有很多的编码知识[…]’. 我们让人们来参加(一项活动), 当时我真的很想知道: 这是真的, 我一直在说什么? 会有40个人出现, 而不是我可以和他们每个人坐在一起…但是人们聚在一起, 而且这种工作方式很有效. 一旦有人获得了, 他们就可以教导他们的邻座.
I’d been saying, “Yeah, anyone can be involved, you don’t have to have a lot of coding expertise […].” We had people sign up to come [to an event] and that’s when I was really wondering: is this true, what I’ve been saying? There are gonna be 40 people who show up, and it’s not like I can sit with each of them…But people came together, and it just sort of worked. As soon as one person got it, they could teach their neighbor.
如果你需要离开你的项目, 不论暂时的还是永久的, 请求别人接管你并不是一件难以启齿的事情.
如果其他人热衷于它的方向, 给予他们提交的权限或这正式的将控制权转交个某个人. 如果有人fork了你的项目, 并且在非常积极的维护它, 考虑从你原始的项目链接到这个fork的项目. 这对那些希望你的项目维护下去的人是很重要的.
@progrium 发现, 记录他的项目Dokku的愿景, 使得即使他离开了这个项目, 这些目标仍然有人继续下去:
我写了一个wiki描述我的目标和为什么我制定这些目标. 因为一些某些原因, 让我很惊讶的是, 项目的维护者们的开发方向都开始往这个方向偏移. 刚好我做了这些这一切就发生了? 不一定. 但它的确让我的项目跟接近我写下的方向.
I wrote a wiki page describing what I wanted and why I wanted it. For some reason it came as a surprise to me that the maintainers started moving the project in that direction! Did it happen exactly how I’d do it? Not always. But it still brought the project closer to what I wrote down.
让其他人构建他们需要的解决方案
如果有一个潜在的贡献者对于你的项目应该怎么做有不同的意见, 你可能需要慢慢的鼓励他们在他们自己fork的项目里操作.
Fork一个项目不一定是一件坏事. 能够复制和修改项目是关于开源的最好的事情之一. 鼓励你的社区成员自己工作, 可以提供他们需要的创造性的出路, 而不会与你的项目的愿景相冲突.
我迎合80%的用例. 如果你是独角兽之一, 请for我的项目. 我不会生气的! 我的公共项目大部分是要解决公共的问题; 我试图通过分工或扩大工作来让事情变得更加容易.
同样的道理也适用于那些真正想要解决方案的用户, 因为他们根本没有足够的带宽来构建. 提供一些API和定制的hooks可以帮助其他人满足他们自己的需求, 而不需要直接修改源码. @orta 发现鼓励CocoaPods导致了一些”有趣的想法”:
几乎是不可避免的, 当一个项目变大, 维护者们必须对于如何采用新代码更加谨慎. 你变得擅长说’NO’, 但很多人都有合理的需求. 所以, 反而你最终将你的工具转换成一个平台.
5.带上机器人
就像其他人帮你做的事情一样, 也有一些不需要人来做的事情. 机器人就是你的朋友. 使用它们可以使你作为一个维护者的生活更容易.
需要测试和其他的检查来提高你的代码质量
可以使得的项目自动化最重要的一个方法就是添加测试.
测试可以使贡献者感到自行, 因为它们不会破坏任何事情. 同时也可以让你快速审查和接受代码变得更容易. 你的反应速度越快, 你的社区就越容易参与.
设置当贡献者提交代码是跑的自动测试, 并确认你的测试可以让贡献者很轻易的在本地跑起来. 要求所有的代码贡献者在他们提交之前必须通过你的测试. 你将帮助设置一个提交的最低质量标准. Gitlab的状态检查可以帮助你确认没有通过测试的代码不会被合并.
如果你添加测试, 确保在CONTRIBUTING文件中解释测试如何运行.
我相信在人开发的代码中测试是必须的. 如果代码是完全正确的, 它就不需要被修改–我们只在一些事错误的时候才写代码, 不论是”它崩溃了”或”它没有这样的功能”. 无论你作出什么改变, 测试对于捕捉任何回归或你意外引入的问题都是必须的. —- @edunham, “Rust’s Community Automation”
使用工具自动执行一些基本的维护任务
关于维护一个受欢迎的项目的好消息是, 有其他的维护者面临过同样的问题, 并构建了一个解决方法.
有各种工具可以帮助自动化维护工作的某些方面, 一些例子:
- semantic-release 自动发布版本
- mention-bot 提到对PR的潜在审查
- Danger 帮助自动化代码审查
对于bug报告和其他常见的贡献, GitHub有issue模板和PR模板, 你可以创建模板来帮你简化收到的消息. @TalAter建了一个选择你自己的冒险指南来帮助你创建自己的issue模板和PR模板.
为了管理你的邮件提醒, 你可以设置邮件过滤来根据优先级管理.
如果你想要更先进一点, 风格指南和linters可以使项目贡献规范化, 并且使得它们更容易审查和接受.
无论如何, 如果你的规范太复杂, 它们会增加贡献的难度. 确保你只是增加了足够的规则, 让每个人的生活更轻松.
如果你不确定使用哪些工具, 参考一起其他受欢迎的项目怎么做, 特别是与你类似的醒目. 例如, 其他Node模块的贡献是什么样的? 使用类似的工具和方法也会让你的贡献者更加熟悉你的流程.
6.可以暂停
开源项目曾经使你快乐, 也许现在它开始让你感到回避或内疚.
也许当你想到你的项目时, 你会感到不堪重负或者越来越恐惧, 与此同时, issuses和PRs也堆积如山.
倦怠是开源工作中一个普遍的问题, 尤其是在维护者中. 作为 一个维护者, 你的幸福对于任何开源项目的生存都是没有商量余地的.
虽然不用说, 休息一下! 你不应该等到感到脑袋都要烧起来才去休息. @brettcannon, 一个Pathon的核心开发者, 决定在14年的自愿开源软件开发工作后进行为期一个月的假期.
就像其他任何类型的工作, 定期的休息会让你头脑清晰, 对你工作更开心, 兴奋.
在维护WP-CLI过程中, 我发现我需要是我自己开心, 并为我的参与设置一个清晰的界限. 最好的平衡点是每周2-5小时, 作为我日常工作表的一部分. 这使我的参与变得充满激情, 并感觉很像一份工作. 因为我优先考录我正在处理的问题, 我可以在我认为最重要的事情上定期取的进展.
—- @danielbachhuber, “My condolences, you’re now the maintainer of a popular open source project”
有时, 当感觉所有人都需要你时, 你很难重开源项目中解脱出来. 人们甚至会试图让你因为离开而感到内疚.
当你离开一个项目时, 尽最大努力为你的用户和社区寻找支持. 如果你不能找到你需要的支持, 那就休息一下. 你休息时记得保持联系, 这样人们就不会因为你缺乏响应而感到困惑.
休息也适用于休假. 如果你不想周末或者工作时间做开源项目的工作, 把这些期望告知别人, 这样别人知道在什么时候不打扰你.
7.先照顾好自己!
维护一个受欢迎的项目不同于早起增长技能阶段, 它没有什么回报. 作为一个维护者, 你将在很少人能够体验到的水平上实践领导能力和个人技能. 虽然管理起来不容易, 但要设定清晰的界限, 并且只关心你觉得舒服的事, 会使你保持快乐, 精力充沛和富有成效.