一个 v1.0 标签引发的思考：开源项目的版本标签与文档一致性
项目迭代到 v2.0 时，最容易出 bug 的不是代码，是文档。
前几天合入 vibe-coding-universal 的一个 PR 让我笑了好一阵。提交信息是 fix: old version label → v1.0 in comparison tables，改动量：四行，每行一个数字。
一个标点的 bug
问题出在 README 的版本对比表。中文版、英文版各一张表，对比 v2.0 相比旧版新增了哪些能力。本该写 v1.0 (旧) | v2.0 (新)，实际写成了 v2.0 (旧) | v2.0 (新) —— 复制粘贴时手滑，把旧版本的标签也写成了 v2.0。
<!-- Before: wrong -->
| Feature | v2.0 | v2.0 |
|---------|------|------|
| Design clarification | ❌ | ✅ 7-round structured dialogue |
<!-- After: fixed -->
| Feature | v1.0 | v2.0 |
|---------|------|------|
| Design clarification | ❌ | ✅ 7-round structured dialogue |
四行 diff，无伤大雅。但这事背后暴露了一个真实的问题：当项目从 v1.0 到 v2.0 的跨度足够大时，连作者自己都会搞混哪个能力是哪个版本的。
v1.0 到 v2.0 发生了什么？
vibe-coding-universal v1.0 做的事很简单：7 轮需求澄清对话，输出一份开发指导书。本质上就是个结构化的调研问卷。
v2.0 把这套逻辑整个推翻重来，加了完整的设计规范链路：
| 维度 | v1.0 | v2.0 |
|---|---|---|
| 需求分析 | 7 轮需求澄清 | 7 轮需求澄清 |
| 设计偏好 | 无 | 新增 7 轮设计偏好澄清（风格/色彩/排版/交互/布局） |
| 设计规范 | 无 | 新增 完整 DESIGN_SPEC.md（10 段：色彩体系、字体栈、组件样式、布局规则、阴影层级、响应式断点） |
| 品牌参考 | 无 | 新增 71 套品牌 DESIGN.md（Stripe/Linear/Airbnb/Apple/Vercel 等） |
| 架构设计 | 无 | 新增 ARCHITECTURE.md |
| 输出格式 | 单一 guide.md | 多文档 Build Spec 包（PRD + Design + Architecture + Tasks + Constitution） |
差距大到什么程度？v2.0 的功能列表几乎是把 v1.0 的每一条都翻了倍。这种量级的变化下，作者写对比表时把旧版本标错，其实挺正常的。
文档一致性：被低估的工程实践
说句实话，"四个字符的标签写错了"这件事，大部分项目根本不会特意提一个 PR。但把它修掉是有意义的，原因有三：
第一，对比表是决策入口。 新手看 README，第一眼扫的就是"What's New"或对比表。如果表头都标错了，读者很难信任整张表后面的数据。
第二，版本标签是沟通契约。 我说"v2.0 支持 DESIGN_SPEC"，你升级到 v2.0 发现确实能用——这是信任。但我说"v2.0 支持某事"其实那是 v1.0 的事，你升级后发现没变化——信任就裂了。
第三，开源项目的信息密度。 源码有 CI、有 review、有测试来保证质量。文档只有作者自己盯着。越是高频迭代的项目，文档和代码的同步就越容易跑偏。
怎么治
两个做法：
把文档变更和功能变更绑在一起。 v2.0 新增 DESIGN_SPEC 能力时，更新 README 对比表的那个 commit，就该和新增 DESIGN_SPEC 的 commit 在同一个 PR 里。合代码的时候顺带看一眼文档，比事后补漏省事得多。
表格类内容用公式化生成。 如果你在用 GitHub Actions 的 release workflow，可以在发布时自动注入版本号到 README 对比表里。比如用
sed把表头的v{old}替换成当前版本、v{new}替换成目标版本。这样写错标签的概率为零。
小结
修一个 v2.0 → v1.0 的标签，改四行，全程不超过 30 秒。但暴露的问题是普遍存在的：代码可以测试，文档只能 review。而 review 自己的文档，谁都容易瞎。
下次写 README 里的版本号时，多看一眼吧。
这篇文章所述内容基于 vibe-coding-universal 的 commit 7c91eae 和项目的实际 README 变更记录。全部数据可复现，无编造。
Top comments (0)