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

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

2025-06-02 07:01:50作者:侯霆垣

项目概述

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. 必须提供descriptiondisplayName字段
  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项目贡献高质量的可靠性规则,共同提升问题检测能力。

登录后查看全文
热门项目推荐

项目优选

收起