DEEPSEEK HARNESS · MAINTENANCE · 0.1.11

维护承诺:这些包会被怎么对待

一个陌生人决定用你的工具时,问的不是「它能做什么」,而是「它明年还在不在」。这份文档回答后者。写它的人只有一个,所以里面关于风险的部分是实话,不是免责声明。

适用于 dsh-vertical-kit、dsh-verify-kit 和 dsh-review-outbox 下的全部 26 个包。


版本怎么走

0.1.x 阶段:次版本号表示可能破坏。在这个阶段我不会假装 semver 的稳定性——一个检查器的规则变严,输出就会变,那对下游是破坏性的,即使函数签名没动。

进入 1.0.0 的条件是三条同时成立:

  1. 规则集合稳定:连续两个版本没有新增 error 级规则(新增 warn 不算破坏,因为 warn 不改变出口码);
  2. 出口码语义冻结:0 干净 / 1 有发现 / 2 用法或读文件错误,这三个数字不再变;
  3. 至少有一个外部使用者报告过它接进了 CI。

在那之前,升级方式是看 CHANGELOG 的「规则变化」一节,不是看版本号大小。

什么算破坏性变更

按影响排序,从最痛到最轻:

变更破坏性为什么
出口码语义改变是CI 靠它判断
已有规则新增 error 级判定是昨天通过的文档今天失败
规则改名是按 rule 名字过滤的用户会静默漏掉
新增 warn 级规则否不改出口码,只看人读的输出
新增可选参数否默认行为不变
报告措辞改变否但会影响按文本匹配的用户,所以 CHANGELOG 里逐条列

规则变动一律写进 CHANGELOG 的「规则变化」表,包括哪条规则从 warn 升到 error、为什么。dsh-outline-lint 0.1.3 就是这么做的:结论规则收窄到报告类交付物,因为原来的域外误报让参考手册也失败。

规则改动的原则

一个检查器的价值在于它能被判定的部分可靠,不在于它抓得多。所以:

弃用怎么做

包被弃用(不再维护但不删)时:

  1. npm 上发一个次版本,README 顶部加一段 > **Deprecated.** 原因 … 取代方案 …;
  2. package.json 加 "deprecated" 字段(npm 会在安装时显示);
  3. 目录条目保留,不主动删除——删掉会让已经装了的人找不到文档;
  4. CHANGELOG 写清最后一个可用版本。

不删包、不改已发布版本的 tarball、不 unpublish。

如果我不再维护

只有一个维护者,这是真实风险,写清楚比藏着好。

已经成立的事实(不依赖我继续存在):

也就是说:代码可以死,工具不会。 一个不再更新的检查器仍然是它发布那天的那个检查器。

如果我消失:欢迎 fork。三件事值得先做——把 author/repository 字段改成你的、把站点的 ORIGIN 改成你的域名、跑一遍 npm test 确认基線。不需要我的许可,MIT 已经给了。

响应预期

现实:这是一个人的项目,没有 SLA,没有值班。下面是我会做的事,不是承诺:

情况我的处理
误报(你的文件没问题却报错)最高优先。规则误报比漏报伤,会修
安装/构建失败优先,通常是我漏了某个 Node 版本的差异
规则建议(想加一条判定)看它是否可从文件本身判定;需要判断力的不做
「能不能支持格式 X」看有没有真实样本;没有样本的格式支持是猜

不做的:不做需要联网或调模型的判定;不做「建议怎么改」,只报「哪一行不符合哪条规则」;不为了抓得多而放宽误报。

怎么判断这些数字可信

这个项目自己的下载数不能当作采用证据——/reading-downloads/ 那页记着原因:26 个包的尾部速率落在彼此的 19% 以内,而目录头部跨 30 倍;均匀性是按作者批量拉取的特征,不是受众的特征。

唯一当作采用信号的是人工决策数(有人读完一份成果、写下证据、点了通过),以及验收单摘要可核对(导出的单子带 SHA-256,文件改动后同一份单子会提示重审)。

两者都不能自动化,也都不能靠下载刷出来。


相关:发布与收录实测手册 · 怎么看自己的下载数 · 生态基线

原文:docs/MAINTENANCE.md