coinagerie-triage

处理 coinagerie 检查失败

失败分为五种，每种都需要不同的处理方式。在打开配置文件之前，先查看发生的是哪一种。

日志内容	类型
Found a glossary out of step with the code	缺少词条和过时词条
Refused a glossary it cannot parse	格式错误的目标
Rejected the configuration	配置错误
Rejected the command line	本次运行无法使用的标志
Found no glossary destination to check	没有 outputs，也没有目标标志

最后三种情况各有一种修复方式：更正配置（coinagerie-configure 技能）、移除冲突的标志（--check 和 --write 不能同时使用，--format 接受 json 或 markdown），或添加目标。

缺少词条

代码使用了词库中没有的词。逐个判断每个词：

这个词是……	处理方式
代码库中的真实术语	--write 会将其作为词条添加，然后为其编写定义（coinagerie-define）
在任何地方含义都相同的语言关键字或样板文本	添加一个 exclude.words 条目，并注明相应原因
没人写过的词头（例如 settings 中的 set）	添加一个 fold 条目，将其映射到人们实际使用的词
偶然出现的词：拼写错误或临时名称	在代码中重命名
来自非代码库自有词汇的文件	为生成文件或 vendored 文件添加一个 exclude.paths glob

要查明词头的来源，请在代码中搜索这个词及其各种形式：复数形式、-ing 和 -ed 形式，以及 camelCase 名称中的组成部分。折叠映射意味着词头可能不会原样出现。

空白词条是检查永远不会收集到的欠账。在添加有含义的词条时，就在同一次修改中为每个词编写定义。

过时词条

词库列出了代码已不再使用的词，而 --write 会将其连同定义一起删除。写入前先查明词条过时的原因：

• 已重命名。 定义属于新词，而重命名是唯一会丢失手写文本的情况。在任何写入之前，手动将旧词条中的粗体词头改为新词：定义会保留下来，检查也会直接通过，无需写入。如果写入已将其删除，请从版本控制中的词库文件历史记录恢复文本。
• 有意移除。 执行写入。追踪代码就是设计目的。
• 被新添加的词语或路径条目排除。 执行写入；删除正是预期结果。
• 扫描范围变了，而代码没变。 如果修改 include、exclude.paths、检出内容或缺失的构建步骤后出现几十个过时词条，说明扫描集合缩小了。恢复扫描范围，然后重新检查：此时写入会删除扫描范围缩小后无法再看到的所有定义。

每次写入前都要查看过时词条列表。写入后，运行 --check 并确认检查通过。

无法解析的词库

错误会指出文件名；如果是 Markdown 格式错误，还会指出行号；不会写入任何内容。可能的原因包括：块中有一行既不是项目符号，也不是缩进续行；同一个词列出了两次；冒号后直接跟了文本，中间没有空格；锚点缺失、重复或顺序颠倒；JSON 无效；或者值不是字符串。手动修复指出的行，其周围的所有定义都会保留。

为了绕过错误而删除整个块或文件，会导致下一次写入从头开始，所有定义都变成空白。

在不同机器上检查结果不一致

• 本地通过，CI 中失败。 扫描的集合不同。可能的原因：本地存在而 CI 中忽略的生成文件夹或构建文件夹，反之亦然；尚未提交的术语表或配置；工作目录不同。分别运行不带参数的 coinagerie --format json 并进行比较。
• 编辑后，缓存的通过结果仍然有效。 在任务运行器的缓存中，配置从其他位置读取的文件（例如父级术语表）必须声明为该检查的输入。
• 父级术语表更改后，某个词又被列为缺失。 如果子级的 exclude.words 读取父级的词条，父级排除的所有词都会被列出。请有意将定义下移，或恢复父级中的词条。

将冲动转化为决策

冲动	应采取的做法
排除所有缺失词条，让检查通过	根据上表逐一决定；被排除的词条将失去定义
扩大 exclude.paths 的范围，直到没有缺失项	只排除不属于代码库自身词条的文件
运行 --write 后继续	查看过时列表以查找重命名，并先编辑每个重命名的主词条
删除整个代码块并重新生成	修复错误指出的那一行
把通过的检查视为完成	检查通过并不代表可以留空定义；请为新增内容编写定义