提交模板生成器

下面是一份可直接落地的提交信息模板与团队最佳实践，符合你给出的规范并适配 monorepo 与 CI/CD 约束。

一、提交信息模板（复制即用）

• 头部 ()!:

• 正文 body（可多行，可省略不相关小节） 背景: <为什么改，用户/业务痛点> 接口/行为变化: <新增/变更/移除；请求/响应/事件；兼容性> 风险: <性能/安全/回滚成本/影响面> 回滚: <如何回滚；是否需数据清理；开关/灰度方案> 测试: <单测/集成/E2E 覆盖点；数据准备> 链接: <设计文档/ADR/PRD/监控面板>

• 页脚 footer BREAKING CHANGE: <迁移指南，替代方案，脚本/步骤> Refs: <issue/PR/任务号/工单> Co-authored-by: <Name >

二、字段与使用规范

• type（限定）
  • feat: 新功能或对外可见行为新增（会触发构建与测试，可能发版）
  • fix: 缺陷修复（构建+单元/集成测试，可能发版）
  • refactor: 内部重构，不改变外部行为（构建+烟囱测试，不发版）
  • chore: 杂项（依赖升级、脚手架、构建脚本等；不默认发镜像）
  • docs: 文档变更（不发镜像）
  • test: 测试相关（不发镜像）
• scope（单仓多服务，二选一且必须是允许集合）
  • auth, gateway, payments, billing, shared-lib, infra, docker, db
  • 说明：数据库迁移仅用 scope=db；服务代码改动用对应服务 scope；二者分开提交
• subject
  • 说明“意图 + 用户影响”，用祈使语气英文动词，如 add/replace/drop/rename/optimize/fix
  • 简洁直达目的，避免行末句号；建议不超 72 字符
• 破坏性变更
  • 在 type(scope)! 使用感叹号，并在 footer 的 BREAKING CHANGE 中给出明确迁移指南
• 原子性
  • 一次提交仅覆盖一个服务的“可回滚单元”；不要跨多个 scope；不要把 DB 迁移与代码变更混在一个提交
• 链接与可追踪性
  • body 链接设计文档/监控面板；footer 的 Refs 关联工单和 PR

三、与 CI/CD 的映射（提交即配置）

• 构建与范围
  • 基于路径变更，仅构建受影响 scope 的服务
• 测试与发布
  • feat/fix: 运行单元+集成测试；若 scope=db，附带迁移检查；可能发布
  • refactor: 触发构建与烟囱测试，不发版
  • docs/test: 不发布镜像
  • chore: 依赖升级或构建脚本变更，不默认发版（可按需要配置）
• 语义化发布
  • semantic-release 针对服务目录独立版本与 CHANGELOG
  • 带 ! 的提交触发对应服务的 major
• 守护
  • commitlint 强制规范；保护分支阻止不合规合并

四、高质量示例

• 正常功能 feat(gateway): add rate-limit headers for public APIs

背景: 公共 API 流量突增，需要向客户端暴露配额信息 接口/行为变化: 响应头新增 X-RateLimit-Limit/Remaining/Reset 风险: 代理缓存命中率可能受影响 回滚: 通过网关开关 gateway.features.rateLimitHeaders=false 关闭 测试: 新增 e2e 覆盖 200/429 两种场景 链接: https://doc.example.com/design/gw-rate-limit Refs: #412

• 缺陷修复 fix(payments): prevent duplicate charge on webhook retries

背景: 第三方重发 webhook 导致重复扣款 接口/行为变化: 无 风险: 幂等键冲突可能导致延迟 回滚: 回滚版本，无数据迁移 测试: 新增集成测试覆盖重复 delivery Refs: BILL-1023

• 重构（不发版） refactor(shared-lib): extract http client and remove dead code

背景: 降低耦合，便于后续替换底层实现 接口/行为变化: 无 风险: 低 回滚: 直接回滚 测试: 保持现有单元测试通过 Refs: #433

• 依赖升级（chore） chore(auth): bump jsonwebtoken to ^9.0.2

背景: 安全修复与性能优化 风险: Token 解析边界行为变化 回滚: 锁回 ^8.5.1 测试: 增加过期与时钟偏移用例 Refs: SEC-221

• 破坏性变更（带迁移指南） refactor(auth)!: split JWT verification into standalone middleware

背景: 提升可插拔性，统一鉴权策略 接口/行为变化: 移除内置 token 解析逻辑，改为策略注入；新增 @svc/auth-mw 包并统一错误码 风险: 旧调用点需要迁移；网关规则需同步 回滚: 回滚到上一个版本并恢复旧导出 测试: 新增中间件集成测试与错误码兼容测试 链接: https://doc.example.com/adr/auth-mw

BREAKING CHANGE: 移除 auth.verifyToken 导出，请使用 @svc/auth-mw#jwtGuard。迁移步骤：

1. yarn add @svc/auth-mw
2. 将所有 verifyToken 调用替换为 jwtGuard()
3. 网关鉴权策略引用改为 auth-mw/jwtGuard Refs: #342

• 数据库迁移（与代码分开） feat(db): add index on transactions(user_id, created_at)

背景: 降低支付流水查询 P95 接口/行为变化: 无 风险: 建索引窗口期写入延迟上升 回滚: DROP INDEX CONCURRENTLY idx_tx_user_created 测试: 预生产回放 1h 生产流量验证 链接: https://doc.example.com/db/migration-2025-01 Refs: PAY-778

• 容器/基础设施 chore(docker): update base image to gcr.io/distroless/nodejs20

背景: 减小镜像与安全基线 风险: 原生依赖运行时差异 回滚: 切回 node:20-alpine 测试: 镜像构建+启动探针烟测 Refs: DEVOPS-55

五、常见约束与避免事项

• 不要在一个提交里修改多个服务或既改代码又做迁移
• 不要使用模糊 subject（如 update、change），应使用 add/replace/drop/rename/fix 等
• 不要超过一屏正文；信息密度优先，突出接口变化/风险/回滚
• 不要在 subject 末尾加句号或使用表情
• 统一小写 type 和 scope；scope 必须在约定集合内

六、提交前快速检查清单

• 这次变更是否仅影响一个 scope？DB 迁移是否独立一个提交？
• subject 是否清晰表达“意图+用户影响”，并使用动词？
• body 是否包含接口变化、风险、回滚及必要链接？
• 是否需要加 ! 且在 footer 写明 BREAKING CHANGE？
• 是否关联了 Refs 以便追踪与流水线可视化？
• 是否具备相应测试覆盖，满足流水线触发要求？

用这套模板与约束，commitlint 可强制格式，CI/CD 能准确基于 scope 与 type 驱动构建、测试与发布，并确保 semantic-release 在 monorepo 下按服务生成独立版本与变更日志。

以下模板与最佳实践面向数据与模型仓库，符合 conventional commits 和你给定的流水线策略。可放入 .gitmessage 作为提交模板并配合 commitlint 校验。

一、提交格式与范围

• 格式: ()!:
• type: feat, fix, docs, test, chore, refactor
• scope: etl, model, feature-store, airflow, monitoring, docs, infra
• 使用 ! 标注破坏性变更（特征/Schema 变更等）

二、模板（可直接粘贴使用） ()!: <影响对象>: <变更动作>；<指标/质量改进>；<影响面>

三、书写要点

• subject 必含影响对象与可量化改进点，如 “用户转化模型：AUC 提升+1.8pp” 或 “在线特征延迟降低30%”
• 语气用祈使句；不加句号；尽量不超过 72 字符
• 明确基线与阈值：写清“对比 vN 基线，AUC +1.8pp（阈值 +0.5pp）”
• 更改特征或 schema 必写 BREAKING CHANGE，并给出迁移脚本路径和下游清单
• 标注数据分区、RunId、模型版本，便于复现与排障
• 一个提交只做一类原子变更；避免同时修改多 scope
• 不提交样本数据/隐私信息；日志与图表放到工单或实验系统，提交里只引用链接/ID

四、示例

1. 常规新增模型 feat(model): 用户转化模型：引入 LightGBM；AUC 提升+1.8pp；推理P95降低12%

• 数据来源与切分: Hive mart.user_events dt in [2025-05-01,2025-05-28]；留出近7天验证；时间窗28天
• 特征与Schema: 新增交叉特征 x_click_7d*x_price；移除低重要度 f_depth；无 schema 破坏
• 训练与验证: lgbm num_leaves=64, lr=0.05, seed=42；对比 v3 基线 AUC 0.789→0.807(+1.8pp)，F1 +1.2pp；阈值 AUC ≥+0.5pp
• 部署与监控: 注册 ModelRegistry user-conv@v4；上线灰度20%；报警阈值：AUC 周下滑>1pp 或 P95>120ms
• 回滚条件与方案: 触发任一阈值回滚至 v3；再训练触发：PSI>0.2 或 2 周定期 Closes: #581 Partition: dt in [2025-05-01,2025-05-28] RunId: mlflow://exp/1234/runs/9ab2c ModelRegistry: user-conv@v4 AirflowDag: train_user_conv@2025-05-29T03:00Z

2. 特征商店破坏性变更（含迁移） refactor(feature-store)!: 重命名特征 fs_user_age_months→user_age_m；缺失策略调整；训练一致性提升

• 数据来源与切分: DWD user_profile 全量；新增生日缺失推断逻辑
• 特征与Schema: 字段重命名；user_age_m 改为整型，空值填充为 -1；历史分区回填
• 训练与验证: 回放近30天线上请求，特征可用率 97%→99.6%
• 部署与监控: 更新在线/离线特征视图与契约；Schema 版本 v2
• 回滚条件与方案: 若下游 5xx >0.5% 或 特征空值 >5% 立刻回滚至 v1；再训练：下游全部迁移后统一重训 BREAKING CHANGE: 重命名与类型变更；迁移脚本 scripts/migrations/fs/v1_to_v2.sql，回填作业 airflow dags/fs_backfill_v2.py；需下游改 SELECT 字段名并更新契约 contracts/fs_user.yaml Closes: DATA-1024 Partition: dt in [2025-05-01,2025-05-30] RunId: fe-sync-2025-05-30-01

3. ETL 修复 fix(etl): 日志解析修复；空值率降至 <0.5%；分区生成稳定性提升

• 数据来源与切分: S3 s3://raw/app-logs/ dt=2025-05-30；修复时区与转义
• 监控与回滚: dq null_rate<0.5%；若>1% 回滚至上版解析器 Closes: OPS-778 Partition: dt=2025-05-30 RunId: etl-logs-20250530-02

4. 文档与测试 docs(docs): 更新特征字典与训练流程图；对齐 v4 指标与阈值 test(model): 增加漂移检测单测与数据契约测试

五、与流水线的映射（提交即策略）

• feat(model), refactor(model): 触发训练+评估，注册模型并做阈值对比
• feat(etl): 跑数据质量校验与样本漂移检测
• docs: 仅构建文档站点
• test: 运行单测与数据契约测试
• 有 BREAKING CHANGE: 阻塞上线，需完成下游兼容检查后再放行
• 使用 conventional commits + commitlint；semantic-release 产出版本与 CHANGELOG

六、检查清单（提交前快速自检）

• subject 是否包含影响对象与量化改进
• 是否标注数据分区、RunId、模型版本
• 是否写明回滚与再训练条件
• 若改特征/Schema，是否加 ! 和 BREAKING CHANGE 及迁移脚本位置
• 变更是否原子且范围明确，避免跨多个 scope
• 所有链接与路径可访问、可复现