detect-secrets项目版本升级规范详解

detect-secrets项目版本升级规范详解

detect-secrets An enterprise friendly way of detecting and preventing secrets in code. 项目地址: https://gitcode.com/gh_mirrors/de/detect-secrets

项目背景与版本控制原则

detect-secrets是一个专注于检测代码库中敏感信息的工具，它采用语义化版本控制(SemVer)规范来管理版本发布。理解其版本升级机制对于项目维护者和使用者都至关重要。

语义化版本控制规范

detect-secrets严格遵守以下版本号变更规则：

1. 主版本号(MAJOR)：当发生破坏性API变更时递增
2. 次版本号(MINOR)：当新增功能或修改基线时递增
3. 修订号(PATCH)：仅修复bug时递增

这种版本控制方式确保了用户能够通过版本号快速判断变更的性质和影响范围。

常见变更场景与版本升级策略

新增过滤器(Filter)

即使不打算默认启用新过滤器，也需要递增次版本号。因为新增过滤器属于功能扩展，可能影响扫描结果。

新增插件(Plugin)

新增插件会修改基线结构，因此必须递增次版本号。插件系统是detect-secrets的核心组成部分，任何扩展都可能影响整体行为。

修改命令行参数

虽然命令行参数变更可能影响用户使用，但除非是破坏性变更，否则只需递增次版本号。这种折中方案避免了过于频繁的主版本升级。

修改默认配置选项

例如调整Base64高熵字符串的检测阈值，这类变更只需递增修订号。因为它仅影响新创建的基线，对已有基线保持兼容。

升级文件机制详解

升级流程

升级系统采用链式处理方式，例如从0.11.0升级到1.0.0时：

1. 先应用v0_12.py将0.11.0升级到0.12.X兼容版本
2. 再应用v1_0.py升级到1.0.X兼容版本

这种渐进式升级确保了不同版本间的平滑过渡。

编写升级文件规范

升级文件必须遵循特定命名规则：v{major}_{minor}.py，并包含一个upgrade函数。该函数接收旧版基线字典作为参数。

重要建议：

• 尽量使用硬编码值而非动态引用
• 避免依赖可能变更的枚举值
• 保持升级脚本的静态性和确定性

版本升级操作指南

预升级检查清单

1. 更新CHANGELOG记录变更内容
2. 编写必要的升级文件确保向后兼容
3. 执行版本升级脚本

发布流程

完成版本升级后，系统会自动触发发布流程，将新版本推送到Python包索引。

最佳实践建议

1. 兼容性优先：除非必要，尽量避免破坏性变更
2. 文档完整：每次版本升级都应详细记录变更内容
3. 测试充分：升级前后应进行充分的兼容性测试
4. 渐进升级：复杂变更可分多个小版本逐步实现

通过遵循这些规范，detect-secrets项目能够保持稳定的版本演进，同时为用户提供平滑的升级体验。

detect-secrets An enterprise friendly way of detecting and preventing secrets in code. 项目地址: https://gitcode.com/gh_mirrors/de/detect-secrets