开源项目的术语表如何统一

本文目录导读：

1. 第一步：确定核心原则与角色
2. 第二步：建立开源的术语管理流程
3. 第三步：利用自动化工具强制统一
4. 第四步：融入项目文化（软约束）
5. 第五步：处理历史债务与冲突
6. 总结：一个实用 checklist

统一开源项目的术语表是一个系统性的工程，涉及流程、工具和社区共识，如果处理不好，会导致文档混乱、API设计不一致、用户困惑甚至贡献者冲突。

以下是分步骤的解决方案，从轻量级到体系化,你可以根据项目规模选择合适的方法。

第一步：确定核心原则与角色

在开始整理之前,必须先明确：

1. 单一来源： 术语表只有一个权威版本（通常是项目根目录下的 GLOSSARY.md 或 TERMINOLOGY.md）。
2. 贡献者共识： 术语定义不是一个人说了算，需要核心维护团队的 Review。
3. 优先级： 优先统一 API/函数名、配置项、用户可见的文案,其次是内部开发文档。

角色分配：

• 术语管理员： 1-2名核心维护者负责审查、合并术语变更。
• 所有贡献者： 有义务在提交PR时,新增或修改术语必须更新术语表。

第二步：建立开源的术语管理流程

建议采用 Propose - Review - Merge - Enforce 的循环。

初始化：创建术语表文件

• 文件名： GLOSSARY.md（标准命名，容易被搜索到），或者 docs/terminology.md。

• 格式示例：

  # 项目术语表
  本文档定义了 [项目名称] 中使用的关键术语，以保持一致性。
  ## A
  - **API**: 应用程序编程接口，在本项目中特指 RESTful API，版本 v3。
  - **Artifact**: 构建生成的产物体，如 .jar 或 .tar.gz 文件。
  ## B
  - **Bucket**: 存储桶，用于存放对象数据。
  - **Backend**: 后端服务，特指处理业务逻辑的微服务。
  ## C
  - **Cluster**: 集群，一组协同工作的节点集合。
  - **Client**: 客户端，可以是 CLI 工具、SDK 或浏览器。

制定命名规范（硬规则）

在术语表中，针对变量、类、命令等,定义一个公共的命名方案，

• 禁止混用： 不要既用 username 又用 user_name，统一采用 snake_case （Python）或 camelCase （JavaScript）。
• 短词优先： 能用 config 就别用 configuration,除非有特殊含义。
• 用户视角： 术语应从用户使用角度出发，而非开发者实现角度，内部叫 DBTable，但对外文档里应该叫 table。

建立变更机制（Pull Request 模型）

当你或社区成员发现术语不一致（比如文档里用了 delete 而 API 里用了 remove）：

1. 提 Issue： 建议先开一个 type: terminology 的 Issue，说明问题，如“统一 delete 和 remove 的使用”。
2. 提交 PR：
   • 修改源代码、文档、注释中所有不统一的术语。
   • 必须 同步修改 GLOSSARY.md：新增术语定义,或更新原定义。
3. 审查： 核心维护者审查时，重点关注：
   • 新术语是否与现有定义冲突？
   • 是否遵循了命名规范？
   • 是否有更好的替代词（如避免用晦涩的缩写）？
4. 合并： 只有术语表同步更新后，才合并该 PR。

第三步：利用自动化工具强制统一

人总会犯错，自动化工具是“守护神”。

推荐工具组合

1. 代码层面检查（Lint）：

   • textlint （通用）+ textlint-filter-rule-comments： 可以写正则规则，禁止在文档中出现 script （要求用 script.js）、legacy （要求用 old）等不推荐词汇。
   • cspell （拼写检查）： 统一单词的大小写和拼写，禁止出现 microservice（应为microservice 或 MicroService）。

2. 文档风格检查（Vale）：

   • 配置 vale.ini 和自定义规则,强制检查特定术语的使用。

   # vale.ini
   StylesPath = .vale/styles
   MinAlertLevel = warning
   [*.{md,yml}]
   BasedOnStyles = Kotoba # 一个社区规则集
   # 自定义替换规则
   core替换.yaml # 禁止使用 old 而推荐用 legacy

   样例规则 （.vale/styles/MyTerms/core替换.yaml）:

   extends: substitution
   message: "请使用 '%s' 而非 '%s'"
   level: error
   swap:
     删除: delete
     移除: delete
     杀掉: delete

3. API Schema 验证：

   如果项目有 OpenAPI/AsyncAPI 规范，可以在 Schema 描述字段中禁止特定词汇。

第四步：融入项目文化（软约束）

光靠工具还不够，要让“统一术语”成为社区共识。

1. CONTRIBUTING.md 强调：

   • 在贡献指南中单独加一节 “术语一致性” ，要求提交前查阅 GLOSSARY.md。

2. Pull Request Template 嵌入检查：

   • 在 PR 模板里加一个复选框：

   - [ ] 我已查阅 `GLOSSARY.md`，确保新增/修改的术语已同步更新。
   - [ ] 我没有引入与现有术语表冲突的新同义词（如使用 `delete` 而非 `remove`）。

3. 开发者文档/聊天频道约定：

   在项目的 Slack/Discord 频道中固定一条消息：“如遇术语分歧，请以 GLOSSARY.md 为准”。

第五步：处理历史债务与冲突

如果你已经有一个混乱的代码库,不要试图一次性全部替换。

1. 批量替换（自动化）：

   • 使用 sed 或 ast-grep 进行大规模替换。强烈建议分模块、分 PR 进行，不要一个超级大 PR。
   • 示例：sed -i 's/old_term/new_term/g' \*.py

2. 建立“黑名单”：

   在 Lint 配置中加入“禁用词列表”，当开发者使用旧的错误术语时，CI 直接报错。

3. 处理不可避免的冲突：

   • 如果社区强烈不同意你的术语（用 service 还是 microservice？），发起一个 RFC 讨论（Request for Comments），投票决定，一旦投票通过,更新术语表并执行。

一个实用 checklist

最终目标： 任何贡献者（包括几个月后的你自己）看到任何一个术语，都能在 GLOSSARY.md 里找到明确的、唯一的解释,并且整个代码库和文档都遵循这个解释。