Linus谈开源治理：不写文档，却铸就千万开发者生态

　　去年一月份，我在西雅图机房替一个trace采样漏报的case做现场复现，空调坏了一半，吹出来的风带着铁锈味。隔壁工位老张一边啃冷掉的牛肉饼一边说：“Linus这老狗又在邮件列表喷人了”，我抬头就看见他转发那封Subject叫“Documentation is for losers”的原始帖——不是转述，是整段copy，连他敲错的两个tab都没删。

　　我原以为这又是典型的老派开源暴君PUA话术，结果翻完三页邮件树，发现底下回帖里有十七个不同公司的人贴出自家内部SRE手册目录，全在对应Linux kernel commit message里某个括号里的单词。有个叫Nina的家伙甚至用kernel v5.12的git blame输出自动生成了她们组的oncall轮值表——就因为某个commit msg里写了“fix race in memcg reclaim path”，而她们的memcg泄漏告警恰好卡在那个路径上。这个我敢打包票，当时她截图里右下角时间戳是UTC+8的凌晨两点零七分，我手机里还存着那张图。

　　优胜劣汰？对。但不是你想象的那种淘汰。是文档缺失逼着所有人去读源码注释、看git log、追perf record的stack dump。去年我们给某电商做分布式链路对齐，对方架构师坚持要“先写好文档再接入”，结果他们自己写的OpenTracing适配层跑三天崩两次，第三次崩溃时我看见他工牌背面用签字笔写着“kprobe挂载点偏移量：0x7f3a1e400b18”。对，就是那个地址。他没查文档，他直接把bpftrace脚本粘贴进生产环境terminal，手敲hexdump -C /proc/kcore | grep 7f3a1e400b18——然后对着输出改代码。那天窗外在下雨，雨点砸在机房玻璃上像弹珠，我数了十八秒没停。

　　不写文档的杀伤力，根本不在“看不懂”，而在“必须自己验证”。我们TraceID传播中间件上线前三周，团队内部跑通率92%，但第三方接入失败率高达67%。最后发现核心问题竟是他们用Java agent劫持了netty的DefaultChannelPipeline，而我们的context propagation逻辑依赖channel.attr()的内存布局——这事kernel里叫“ABI稳定性”，但在JVM世界，没人告诉你哪个attr名会被hotspot优化掉。最后是个实习生在翻openjdk源码时，发现某次G1 GC调优补丁偷偷改了ObjectHeader大小。这玩意儿根本不会出现在任何release note里。我后来问那个实习生怎么想到查那个补丁，他说：”因为Linus说‘read the fking source’，我就真去看了。”

　　前两天跟某云厂商做联调，他们总监掏出一本三百七十二页的《可观测性接入规范V3.2》，纸面锃亮，边角都包了铝箔。我翻到第87页“TraceContext透传兼容性要求”，底下印着“请严格遵循OpenTelemetry Spec v1.27.0 Section 4.3”。结果他们SDK里实际实现是v1.22.0的语义——就因为Spec里4.3节有个note被他们的文档团队当废话删了：“Note: implementers may defer adoption until vendor X ships v2.1”。可Vendor X上个月刚倒闭。桌上那盒麻辣烫盖子没扣严，红油渗出来，在“兼容性要求”标题下面拖出一道细长的痕迹。

　　真正踩坑的从来不是新手。去年双十一前，某支付平台的trace采样率突然从千分之一飙到百分之三十七，链路爆炸式增长，jaeger UI直接卡死。运维喊我去查，结果发现是他们自研的sampling policy里，把`ctx.Get("env")`改成`ctx.Get("ENVIRONMENT")`，只因某次合并冲突时误删了.env文件里的一行小写变量声明。这个改动没进任何change log，更没人写文档说明这个字段是采样策略的主开关——它就躺在那段二十行的if-else嵌套里，靠一个go test case覆盖。我当时盯着那个test名字看了三遍：`TestSampleRateWithValidEnvAndMissingFallback`。而那个fallback，压根没被任何prod config触发过。电话响了，是客户支持组打来的，问我们“为什么trace显示用户下单成功但银行流水没生成”，我没接，让老张去听。他左手拿着耳机，右手在便签纸上画了个圆圈，中间写“panic: context canceled”，然后把纸揉成团扔进了装外卖汤盒的垃圾桶。

　　其实我早该想到的。2017年在奥斯陆Trace大会听Jaeger团队分享，台下有人举手问“你们怎么保证span format向后兼容”，主讲人笑了，说：“我们不保证。我们只保证每个breaking change后面，跟着至少两个真实用户的bug report和PR。” 台上灯光太亮，照得他T恤领口发白，我注意到他右耳垂上有颗痣，很小，但每次他歪头笑就特别明显。

文章配图，仅供参考

　　所以别跟我说什么“生态建设需要文档基建”。基建？我们基建是拿jstack堆出来的，拿strace抓出来的，拿/proc/kallsyms里一个地址一个地址撞出来的。昨天我看到Linus在回复某个RFC patch时写：“If you can’t grep it, it doesn’t exist.” ——这句话底下有三百多个+1，其中四十六个来自各大厂的observability team lead。但谁也没提一句，他们服务器监控报警里，那个持续三年未处理的“/proc/sys/kernel/perf_event_paranoid == 3”警告，至今还在dashboard上闪着红光。

　　接下来我要把我们trace agent里所有带// TODO的注释删掉，换成真实的linux commit hash。比如原来写“// TODO: fix context propagation on async callbacks”，现在改成“// See torvalds/linux@f2d4a8b: sched/core.c#L7892”。反正工程师要么查hash，要么放弃——总比留个空洞的TODO等着明年被新同学删掉强。对了，刚才老张又接了个电话，说了句“嗯，知道了”，然后放下手机，撕开一包瓜子，吐壳的时候把最后一颗塞进了自己左耳朵里。

（编辑：站长网）

【声明】本站内容均来自网络，其相关言论仅代表作者个人观点，不代表本站立场。若无意侵犯到您的权利，请及时与联系站长删除相关内容!