GitHub Linguist 注册指南・光明语言模块参考
版本：v1.0 ｜ 更新日期：2026-10-07
用途：记录如何让 GitHub Linguist 识别 .light 扩展名，供后续光明模块注册工作参考
一、什么是 GitHub Linguist？
GitHub Linguist 是 GitHub 用来识别仓库中代码语言的开源库。它决定了：
-
仓库首页右侧的语言统计条显示什么语言
-
代码文件的语法高亮
-
GitHub 上按语言搜索的功能
重要 ：.gitattributes 的 linguist-language 属性只能映射到 Linguist 已经认识的语言，不能创建新语言。要让 GitHub 认识一门全新的语言，必须向 linguist 仓库提交 PR。
二、注册新语言需要准备什么？
| # | 材料 | 说明 | 光明现状 |
|---|---|---|---|
| 1 | TextMate Grammar 文件 | .tmLanguage.json 或 .tmLanguage 格式，定义语法高亮 |
✅ 已有：vscode-extension/syntaxes/light.tmLanguage.json |
| 2 | Grammar 许可证 | 必须是宽松开源许可（MIT/BSD/Apache），允许再分发 | ✅ MIT 许可证 |
| 3 | Sample 示例文件 | 5-10 个小而完整的示例，展示语言典型语法 | ✅ 已准备 6 个（见 samples/Light/） |
| 4 | languages.yml 条目 | 在中央注册表中添加一条配置 | ✅ 已准备 |
| 5 | Proof of Usage | 有一定数量的公开仓库在用这门语言 | ⚠️ 较弱，需要积累 |
三、完整注册步骤
Step 1：Fork 官方仓库
在 GitHub 上 fork github-linguist/linguist 到自己的账号下。
https://github.com/github-linguist/linguist → 点 Fork 按钮Step 2：克隆到本地
git clone https://github.com/你的用户名/linguist.git
cd linguistStep 3：添加 Grammar 文件
把你的语法高亮文件放到 vendor/grammars/你的语言名/ 目录下。
光明的做法：
vendor/grammars/Light/
├── light.tmLanguage.json ← 从 vscode-extension/syntaxes/ 复制过来
└── LICENSE ← 许可证说明注意：Grammar 必须有许可证，否则审核不会通过。
Step 4：添加 Sample 示例文件
在 samples/你的语言名/ 目录下放 5-10 个示例文件。
要求：
-
每个文件要小（几行到几十行）
-
要能展示语言的典型语法特征
-
覆盖不同方面：基础语法、函数、类、高级特性等
光明准备的 6 个示例：
samples/Light/
├── hello.light ← 基础输出、变量、循环、条件
├── fibonacci.light ← 函数、递归
├── class.light ← 面向对象
├── l3_sql.light ← L3 领域嵌入（SQL）
├── l4_python.light ← L4 外语引用（Python）
└── stdlib_demo.light ← 标准库使用Step 5：修改 languages.yml
打开 lib/linguist/languages.yml，按字母顺序找到正确位置，插入语言条目。
光明的条目：
Light:
type: programming
color: "#FFB300" # 琥珀金色，对应"光明"的意象
aliases:
- lightlang
- guangming
extensions:
- ".light" # 主扩展名放第一位
tm_scope: source.light # 与 grammar 文件的 scopeName 一致
ace_mode: text
codemirror_mode: text
codemirror_mime_type: text/x-light字段说明：
| 字段 | 说明 |
|---|---|
type |
programming / markup / data / prose |
color |
仓库语言条显示的颜色，选一个独特的 |
aliases |
别名，方便搜索 |
extensions |
文件扩展名，主扩展名放第一位 |
tm_scope |
与 grammar 文件的 scopeName 一致 |
ace_mode |
ACE 编辑器模式，没有就填 text |
codemirror_mode |
CodeMirror 模式，没有就填 text |
language_id |
提交后由维护者分配，先不填 |
Step 6：提交 PR
向 github-linguist/linguist 仓库提交 Pull Request。
PR 标题 ：Add Light programming language (.light)
PR 描述模板：
## Description
This PR adds support for the Light programming language (光明语言),
a Chinese-keyword, multi-paradigm programming language.
- Repository: https://github.com/skywalk163/light
- License: MIT
- Extensions: .light
## Checklist
- [x] Grammar provided (TextMate tmLanguage format)
- [x] Sample files included (6 samples covering core features)
- [x] languages.yml entry added
- [x] Grammar license confirmed (MIT)
## Grammar Source
Sourced from the official VS Code extension:
https://github.com/skywalk163/light/tree/main/vscode-extension/syntaxes四、临时替代方案（不等官方注册）
如果不想等几周到几个月的审核，可以先用 .gitattributes 做临时映射：
# 把 .light 文件临时算作 Python
*.light linguist-language=Python效果：
-
✅ 仓库语言统计条不会全是 "Other"
-
❌ 显示的语言名不对（显示 Python 而不是 Light）
-
❌ 没有专属语法高亮
适用场景：过渡时期用，正式注册通过后删除此文件。
五、可能遇到的问题
| 问题 | 应对方法 |
|---|---|
| 命名冲突 | 检查 languages.yml 中是否已有同名语言。如果有，用别名或更独特的名字 |
| Proof of Usage 不够 | 多创建几个用该语言写的公开 demo 仓库，增加 GitHub 上的使用量 |
| 审核慢 | Linguist PR 通常要几周到几个月，耐心等待。期间用 .gitattributes 临时方案 |
| Grammar 不符合要求 | 确保 grammar 是标准的 TextMate 格式，scopeName 正确 |
六、光明语言注册进度跟踪
| 步骤 | 状态 | 完成时间 |
|---|---|---|
| 1. Fork linguist 仓库 | ⏳ 待手动操作 | --- |
| 2. 准备 grammar 文件 | ✅ 已完成 | 2026-10-07 |
| 3. 准备 6 个 sample 文件 | ✅ 已完成 | 2026-10-07 |
| 4. 修改 languages.yml | ✅ 已完成 | 2026-10-07 |
| 5. 提交 PR | ⏳ 待手动操作 | --- |
| 6. 等待审核通过 | ⏳ 待审核 | --- |
| 临时方案：.gitattributes | ✅ 已完成 | 2026-10-07 |
七、相关文件位置
| 文件 | 路径 |
|---|---|
| languages.yml 条目备份 | wikipedia_draft/linguist_languages_yml_entry.yml |
| .gitattributes 临时方案 | light-merge/.gitattributes |
| linguist 本地克隆 | linguist_fork/ |
| Sample 文件 | linguist_fork/samples/Light/ |
| Grammar 文件副本 | linguist_fork/vendor/grammars/Light/ |
备注
：本文档供光明语言后续的模块注册、生态建设参考。如果未来有其他语言变体（如 LightScript、LightML 等）需要注册，可以复用本指南的流程。