为语言检测代码库添加文件扩展名或新语言

## 梳理检测的各部分由哪些文件和工具负责 编辑前，先确定语言检测各部分分别由哪些文件和工具负责： - 管理名称、扩展名、文件名和语言属性的语言注册表； - 用于歧义文件的启发式规则及其实现； - 统计分类器及其真实样本语料库； - 用于语法高亮的语法注册表； - 随项目提供的语法源和缓存的许可证数据； - 维护脚本、测试和持续集成入口。 把这些部分视为相互协调的约定。一次元数据变更可能不只是孤立编辑，还需要样本、启发式规则、生成的标识符、语法数据、测试和证据。 ## 在代码库的开发容器中准备环境，并使用其脚本 如果可用，应优先使用代码库维护的开发容器或托管环境。该环境应提供声明的语言运行时、软件包工具、容器运行时、原生库和项目的全部依赖项。 在本地工作时： 1. 运行标准初始化命令。 2. 通过代码库的依赖运行工具调用库或命令行工具。 3. 使用已记录的维护脚本，不要手工复现其效果。 4. 确认编码检测、代码库访问或语法处理所需的原生依赖项均已就绪。 不要把本地临时调用成功视为受支持环境也一定能通过的证明。 ## 按字母顺序为现有语言添加扩展名，并附上真实样本 为现有语言添加文件扩展名时： 1. 更新权威语言条目。 2. 按要求以区分大小写的字母顺序排列扩展名列表，大写排在小写之前，主要扩展名排在最前。 3. 在所属语言下添加能够代表真实使用情况的样本文件。 4. 如果该扩展名还被另一种语言使用，请提供至少两个样本，并添加消歧启发式规则。 5. 为元数据和启发式行为添加或更新测试。 不要使用简单问候程序等教程中的常见示例作为分类器证据。样本必须反映检测器应该识别的真实代码。 ## 添加新语言时登记语法，并用脚本生成ID 新语言所需的不只是注册表标签： 1. 添加语言条目，但将其生成标识符保持为未设置状态。 2. 通过标准语法工具注册已获批准且兼容的语法高亮定义。 3. 从可验证的原始来源添加有代表性的样本文件。 4. 运行标识符生成脚本，不要手工分配标识符。 5. 如果有任何扩展名被多个语言使用，请提供至少两个样本，并添加经过测试的消歧规则。 6. 一并验证元数据、语法注册、分类结果和生成的变更。 保持注册表头部指引、字段要求以及区分大小写的排序方式不变。 ## 为共用扩展名的语言编写带测试的正则判定规则 启发式规则应解决真实歧义，同时避免造成大范围误报。 - 匹配能够区分竞争语言的最小特征证据。 - 确保每个模式的运行时间与输入大小保持线性关系。 - 避免容易受到正则表达式拒绝服务攻击的结构。 - 只使用代码库规定的正则表达式引擎所支持的语法。 - 测试正例、竞争语言案例和接近判定边界的案例。 - 当启发式规则或样本变更可能改变检测行为时，运行分类器交叉验证。 每条启发式规则都必须有测试。能够识别目标却同时匹配无关文件的规则不可接受。 ## 生成的文件不要手改，用维护命令重新生成 不要手工编辑生成的注册表、模块声明、随项目提供的语法内容或缓存的语法许可证文件。添加或替换语法时，应使用负责该内容的维护命令，并审查该命令产生的所有变更。 接受某个语法定义前： - 确认它与项目所用的语法高亮格式兼容； - 确认其许可证位于批准列表中； - 保留权威原始来源URL和许可证记录； - 在受支持的容器环境中运行该语法专用的验证。 如果生成结果有误，应修正源输入或生成工作流程，而不是直接修补生成结果。 ## 运行分类器交叉验证和完整测试套件 先运行范围最小的相关检查，再执行代码库要求的全部验证： 1. 验证修改过的元数据和排序。 2. 运行新样本和启发式规则的测试。 3. 当检测边界可能移动时，运行分类器交叉验证。 4. 通过标准依赖运行工具执行完整测试套件。 5. 确认持续集成通过相同的必需阶段。 检查失败原因，包括误报、生成文件偏移、缺少原生依赖项、无效语法数据，以及对无关语言的意外变更。 ## 提交前出示使用量证据和样本许可证 提交贡献请求前： - 使用提供的请求模板，只移除无关部分； - 为每个新增扩展名链接公开搜索证据，并排除分叉代码库； - 对常见扩展名展示至少2000个已索引文件；对通常每个代码库只出现一次的名称展示200个文件； - 检查这些文件是否合理分布于不同用户与代码库组合，并考虑占比异常高的用户； - 将每个样本链接到其原始来源，而不是贡献所用的分叉代码库； - 分别说明每个样本代码的许可证； - 通过全部必需测试和持续集成检查； - 保持变更范围集中，不要混入无关重构。 如果有任何要求未满足，就不要提交请求。说明缺少哪项证据、许可证、测试或范围条件，以及必须先完成什么。