如何给 Meltype 做贡献：从添加词典词条到提交 PR 的完整清单（含 CLA 说明）
如何给 Meltype 做贡献：从添加词典词条到提交 PR 的完整清单（含 CLA 说明）
Meltype 是一款"像融雪一样"打通半角/全角边界的开源日文输入法，只打罗马字就能自动判断日文与英文。本文是一份面向新手的贡献指南：从在 dictionaries/ 里添加词典词条，到撰写 Pull Request 并通过 CLA（贡献者许可协议）检查，带你走完整条贡献路线。
🤝 Meltype 接受哪三种贡献？
无论你是否会写代码，都有参与方式（详见 CONTRIBUTING.md）：
| 贡献方式 | 门槛 | 说明 |
|---|---|---|
| 报告 Issue | ⭐ 无需编程 | 用 Issue 模板说明"哪个应用、打了什么、发生了什么" |
| 添加词典词条 | ⭐⭐ 只需改文本文件 | 向 dictionaries/ 提交词条，走 PR 或 Issue |
| 提交代码 PR | ⭐⭐⭐ 需跑通测试 | 修改前先在 Issue 下留言认领，避免多人重复修 |
💡 即使没有 GitHub 账号，也可以直接通过 Meltype 托盘菜单的「不具合の報告・提案...」发送报告，内容会自动转为 Issue（实现见 tools/report-form/）。
📚 添加词典词条：5 分钟上手的贡献
词典是 Meltype 判定与转换精度的核心，全部是纯文本文件，放在 dictionaries/ 目录下。
常见词典文件与格式速查
| 文件 | 格式 | 示例 |
|---|---|---|
| dictionaries/candidates.txt | 读音 候选 候选…（空格分隔，读音用平假名） |
とうてん 読点 当店 、 |
| dictionaries/translations.txt | Tab 分隔 3 列：写法 / 词性 / 英译 | 明白 na obvious,clear |
| dictionaries/meanings.txt | Tab 分隔 3 列：写法 / 读音 / 释义 | あけましておめでとうございます 新年挨拶。 |
| dictionaries/english-words.txt | 每行一个全小写英文单词 | abandon |
| dictionaries/phrases.txt | Tab 分隔短语 | 以 # 开头的行为注释 |
⚠️ 添加前注意两点：
- 词性只能用
n/na/i/v/adv之一（translations.txt）； - 禁止把其他输入法或市面 IME（如 ATOK、Microsoft IME）的词典内容让 AI 转写后直接添加——版权不符的词条无法被接收。若基于 JMdict、Wiktionary、Unicode CLDR 等公开数据制作大词典，需在 PR 中写明数据来源与许可证，并附上生成脚本（放在 tools/ 目录，参考 tools/make-meanings.mjs、tools/make-translations.mjs）。
本地一键校验词典格式
提交前先跑校验脚本，和 PR 自动检查用的是同一套规则：
node tools/check-dictionaries.mjs
脚本会报告读不出的行（错误，阻断合并）和"建议修改"的行（警告）。具体格式规则定义在 tools/check-dictionaries.mjs 中，可以对照查看。
✅ 提交 PR 前的完整清单
1. 先认领 Issue
如果你打算修某个 Issue，先在该 Issue 的评论里留言说明由你负责，再动手。这是为了防止多人同时修同一个问题。
2. 新文件要加版权头（写自己的名字！）
新建的源码文件头部必须包含两行注释，版权人写你自己的名字（GitHub 用户名即可），不要照抄原作者：
// SPDX-License-Identifier: GPL-3.0-or-later
// Copyright (C) 2026 你的名字
3. 关于 CLA（贡献者许可协议）
Meltype 以 GNU GPL v3 开源，但作者也会单独批准无法接受 GPL v3 条件的用户（如非公开使用）。为了持续这么做，首次提交 PR 的每个贡献者都需要同意 CLA：
- PR 创建后，机器人会自动在 PR 下贴出 CLA 文案；
- 你只需回复一行：
CLA に同意します（或英文I agree to the CLA）； - 同意会被记录在
cla-signatures分支，之后的 PR 都不需要再签； - 未同意前，PR 上的"CLA"检查项会保持失败状态，PR 无法被合并。
CLA 的核心内容：① 贡献是你自己创作、有权提供；② 授予作者复制、修改、分发该贡献的免费、不可撤销权利（含 GPL v3 之外的授权）；③ 贡献的版权仍归你所有。
4. PR 数量小贴士
一次提交 3 个以上 PR 时，请额外创建一个包含全部修改的合并 PR，以减少冲突解决对维护的负担。
5. 使用了 AI？必须声明
- AI 辅助开发是被欢迎的（官方提交也标注了
Co-Authored-By），但务必在 PR 中写明用 AI 做了哪些部分（代码草稿/测试/文档/词典等）； - 未声明但内容明显是 AI 生成的 PR，可能被直接关闭；
- 只提交自己理解并能解释的内容，动手运行测试验证过效果；
- 新功能、新设置请先开 Issue 提案沟通；修 bug、加词典、小改进可以直接提 PR；
- 注意：Meltype 承诺输入内容只在本地处理，不接受会把输入发到外部服务的功能。
🤖 机器人命令与自动检查
在 Issue/PR 评论的第一行输入以下命令，机器人会自动执行并回复结果：
| 命令 | 作用 | 可用对象 |
|---|---|---|
/repro <键入内容> [space|enter|none] |
用最新代码试打并返回结果 | 任何人 |
/explain <键入内容> |
逐字符展示 IME 自动切换判定理由 | 任何人 |
/ca <键入内容> |
展示词切分与首词候选（最多 9 个） | 任何人 |
/help |
查看全部命令 | 任何人 |
PR 创建后会自动触发以下检查，其中"精度比较"会用主分支与你的 PR 做质量测试对比，出现新的失败案例即判定不通过：
| 检查项 | 触发条件 | 内容 |
|---|---|---|
| build / test | 总是 | Windows·Linux·Mac 三平台构建与测试 |
| 词典格式 | 改动 dictionaries/ |
检测不可读行、非平假名读音、重复词条 |
| 精度比较 | 改动判定/转换核心或词典 | 与 main 分支对比质量测试结果 |
| 报告复现 | 总是 | 验证 PR 正文"输入 → 期望"及 Fixes #12 关联的报告 |
| CLA | 首次贡献 | 贡献者许可协议检查 |
📋 贡献路径总览
- 浏览 CODE_OF_CONDUCT.md 了解行为准则；
- 挑选贡献方向：报 Issue → 加词典 → 提代码 PR；
- 改词典：对照格式表添加词条，本地运行
node tools/check-dictionaries.mjs校验； - 提 PR：先认领 Issue，新文件加版权头，声明 AI 使用情况；
- 首签 CLA：回复一行同意语，后续一劳永逸；
- 等待自动检查通过，维护者审查合并。
想进一步本地构建运行，可参考 docs/DEVELOPMENT.md 中的构建与测试命令（如 dotnet run --project src/Meltype.Tests）。欢迎加入，一起让 Meltype 的输入体验像融雪一样顺滑！❄️