统一文档根目录:2.49.0 中 docs/ 更名为 documentation/
一个框架曾有两个含义不同、名称各异的文件夹。2.49.0 版本将它们合并为单一的 documentation/ 根目录,按 Diátaxis 四大类别拆分文档,并推出 /dr-doctor 自愈功能,让你的仓库无需手动编辑即可跟进。
Datarim 2.49.0 做了一项结构性变更,并在所有地方贯彻到底:文档根目录从 docs/ 更名为 documentation/。这是对规范的一次破坏性变更,因此值得解释为什么一次文件夹更名会获得一个小版本号提升和一条硬切换的兼容性规则。
问题所在:两个文件夹,两种含义,一场迟早发生的冲突
一个 Datarim 项目实际上有两个文档面,它们以不同的名称存在,且从未统一:
docs/—— 框架自身的产品文档:入门指南、命令与技能参考、解释性文章。documentation/—— 使用者的知识库:归档的任务记录、授权、基础设施笔记 —— 一个使用 Datarim 的项目的已提交历史。
两个根目录,两套契约,没有共享词汇。每个新项目都必须了解“docs”在框架内部意味着一种东西,而它自己的长期文档则完全在别处。漂移检测器能看出项目有一个 docs/ 文件夹,但对它与 documentation/ 的关系没有任何意见。这种分裂是每个仓库永远要支付的一笔小税。
决策:重命名并合并到一个根目录下
2.49.0 没有保留两个名称,而是让 documentation/ 成为整个生态系统的唯一规范文档根目录。框架的产品文档移入其中,按四个 Diátaxis 类别组织:
documentation/tutorials/—— 面向学习的演练(入门指南、用例)documentation/how-to/—— 面向任务的配方(发布流程、验证、演进日志)documentation/reference/—— 面向信息的查阅(命令、技能、CLI、验证器契约)documentation/explanation/—— 面向理解的背景(流水线、consilium、规范可追溯性)
使用者现有的知识库不会移动 —— 其任务归档仍保留在 documentation/archive/。重命名后的产品文档只是成为它的同级。为防止两套契约再次冲突,现在保留了四个名称:Diátaxis 类别不得命名为 archive、evolution、release-audit 或 ephemeral。一个根目录,清晰划分,没有重叠。
Git 历史全程保留 —— 每个文件都通过 git mv 移动,因此 git log --follow 仍能追溯到重命名之前。
硬切换 —— 但绝不只责备而不给补救
兼容性立场是彻底断代:漂移检测器现在将仍使用旧版 docs/ 的仓库视为漂移。硬切换只有在它标记的问题确实可以修复时才公平 —— 标记问题却不给修复路径只是唠叨。因此 2.49.0 在同一版本中提供了补救措施。
/dr-doctor 新增了一个可选的文档迁移自愈流程。将它指向仍使用 docs/ 的使用者仓库,它会执行框架对自身所做的相同迁移:
- 检测布局 —— 旧版
docs/、部分迁移的半完成状态,或已迁移的仓库(此时为干净的空操作)。 - 迁移使用
git mv+ Diátaxis 拆分(已知文件映射到其类别;未知文件落入how-to/并带有审查标记)+ 锚定引用重写。 - 验证结果是否符合引用 linter —— 如果任何检查失败,回滚到备份 tarball 中迁移前的精确目录树。
它是幂等的(运行两次,第二次不做任何事)且回滚安全(验证失败绝不会让你处于半迁移状态)。它刻意作为一个独立的同级工具,而不是作为新模式附加到操作文件 doctor 上 —— 产品文档物理上位于框架自身状态目录之外,将内容迁移混入模式迁移会模糊框架刻意保持的边界。
如何迁移你的仓库
如果你的项目仍使用 docs/,升级只需一条可选命令:
- 运行
/dr-doctor;它会将旧版docs/报告为可用的迁移。 - 接受迁移;doctor 会按 Diátaxis 拆分将你的文档移入
documentation/并重写引用。 - 如果迁移后检查失败,目录树会自动恢复 —— 不会留下半完成状态。
由 /dr-init 脚手架生成的新项目已经以 documentation/ 起步。那里无需操作。
为何重要
这项变更在 diff 上很小,在清晰度上很大。一个文档根目录意味着“这份文档该放在哪里?”只有一个答案 —— 产品文档按 Diátaxis 类别,项目历史放在 archive/ 下,两者都在 documentation/ 下。漂移检测器、脚手架、授权和 doctor 现在都指向同一个地方。完整条目请参阅变更日志。