深入理解prequel-dev/cre项目：规则开发与贡献指南

项目概述

prequel-dev/cre项目是一个专注于构建通用可靠性枚举(Common Reliability Enumerations)的开源项目，旨在为问题检测社区提供标准化的规则定义和分类体系。该项目通过YAML格式定义规则，并使用专门的工具链进行验证和构建。

规则开发流程详解

1. 前期讨论与问题定义

在开始编码或创建新规则前，强烈建议先通过issue进行讨论。这种做法有三大优势：

1. 早期验证：确保规则设计符合项目整体方向
2. 环境兼容性：讨论规则在不同环境下的适用性
3. 效率提升：避免后期大规模重构的风险

有效的issue应包含以下要素：

• 清晰的问题描述
• 重现步骤（如果是bug）
• 相关日志或代码片段（脱敏后）
• 预期与实际行为的对比

2. 规则ID生成机制

项目采用独特的ID生成系统，包含两种类型：

CRE ID格式

采用CRE-YEAR-0123的格式，由项目维护人员在PR审核时分配。

规则ID生成

使用项目内置的ruler工具生成：

$ ./bin/ruler id
DCejCw6644SvCgdJ5XT3bm

技术要点：

• ID长度为12个字符以上
• 仅支持字母数字组合
• 通过哈希算法保证唯一性

3. 分类与标签系统

项目采用分层分类体系：

• categories.yaml：定义宽泛的问题类别
• tags.yaml：定义具体的技术或问题标签

开发新规则时需注意：

1. 确保标签/分类名称全局唯一
2. 必须提供description和displayName字段
3. 保持分类的通用性和标签的专一性

开发环境配置

1. 模式验证配置

为提高开发效率，建议在VSCode中配置YAML模式验证：

1. 安装Red Hat的YAML扩展
2. 在settings.json中添加：

{
    "yaml.schemas": {
        "https://docs.prequel.dev/cre-schema.json": [
            "/rules/cre-*/*.yaml"
        ]
    }
}

此配置将对rules/cre-*目录下的YAML文件实施模式验证，确保规则定义符合项目规范。

2. 构建系统

项目提供两种构建方式：

使用预编译的ruler工具

ruler-linux-amd64 build -p rules -o ./bin

从源码构建

要求Go 1.24.1+环境：

$ make

构建过程执行以下验证：

1. 检查所有引用的标签和分类是否存在
2. 确保CRE和规则ID无重复
3. 验证规则语法和语义正确性

测试规范

项目采用严格的测试要求：

1. 必须包含：test.log文件，记录触发规则的正面条件
2. 建议包含：test-fp.log文件，记录可能产生误报的场景

测试执行命令：

cd ./tests
LOG_LEVEL=INFO go test

代码提交与评审

1. 提交规范

• 频繁提交，保持小颗粒度变更
• 编写有意义的提交信息，避免"update"等模糊描述
• 每个提交应包含变更内容和原因说明

2. PR审核流程

1. 将本地分支推送到个人仓库
2. 针对main分支发起PR
3. 关联相关issue（如"Closes #123"）
4. 等待审核并参与讨论

审核重点包括：

• 规则设计的普适性
• 对误报/漏报的影响评估
• 代码/规则质量

项目采用squash merge策略，PR中的所有提交将被合并为一个提交。

开发者注意事项

1. 协议签署：新贡献者需签署贡献者许可协议(CLA)
2. 响应延迟：如issue长时间未获响应，可通过评论提醒或@维护人员
3. 协作沟通：鼓励开发者在实现前通过issue讨论方案

通过遵循这些规范，开发者可以更高效地为prequel-dev/cre项目贡献高质量的可靠性规则，共同提升问题检测能力。