SVN提交规范

lishihuan大约 9 分钟

SVN提交规范

1. 目的

本规范用于统一项目组 SVN commit -m 提交说明的写法，降低以下问题：

  • 提交标题过短，看不出改了什么
  • 提交说明过散，无法快速定位变更原因
  • 一次提交包含多个主题，后期难追踪、难回滚
  • 线上问题回查时，看不到“为什么改、改了哪里、风险点在哪”

目标是让每一次提交都做到：

  • 一眼看懂本次改动主题
  • 能快速判断影响范围
  • 能支持后期排查、追溯、回退、交接

2. 适用范围

适用于本项目所有代码、配置、脚本、文档相关的 SVN 提交。

包括但不限于：

  • 后端 Java 代码
  • 前端页面与脚本
  • SQL、配置文件、脚本文件
  • 接口文档、设计文档、测试文档

3. 总体原则

提交说明遵循以下原则：

3.1 一次提交只表达一个主题

推荐：

  • 一个缺陷一个提交
  • 一个重构主题一个提交
  • 一个需求点一个提交

不推荐：

  • 同一次提交既修 bug，又改样式，又调配置，又补文档

3.2 标题优先写“改动意图”，不要只写“改了什么”

推荐：

  • AI填单：收敛选择挂起状态来源，拆分 pendingAction 与运行态
  • 日计划：修复树字段 follow-up 下人员未找到后续接错误

不推荐：

  • 修改代码
  • 调整一下
  • 优化
  • bug修复

3.3 描述应可追溯

提交说明至少应回答 3 个问题：

  • 为什么改
  • 改了哪一类逻辑
  • 影响了哪些模块或链路

3.4 标题要让人“脱离上下文也能看懂”

查看提交历史时，阅读者往往不知道你当时在处理什么问题，所以标题不能依赖口头上下文。

4. 推荐格式

推荐统一使用“两段式”或“三段式”提交说明。

4.1 简版格式

适用于小改动、单点修复：

模块/主题：改动目的

示例：

  • AI填单：修复树字段人员选择翻页后候选丢失
  • 日计划：修复保存后未回显工作负责人问题
  • 网关：补充生产环境超时配置

4.2 标准格式

适用于常规开发提交，推荐优先使用：

模块/主题：改动目的

- 原因/背景- 主要改动- 影响范围

示例：

AI填单：收敛选择挂起状态来源，拆分 pendingAction 与运行态

- 解决 pendingAction 同时承担协议信封与运行态快照导致的双写和易错问题- 将 resolvedSelections、候选快照、树 follow-up 运行态统一收敛到 EntitySelectionState- 影响通用下拉、树字段选择、AI follow-up prompt 上下文构建链路

4.3 完整格式

适用于重构、跨模块联动、大改动：

模块/主题：改动目的

- 背景：为什么要改- 改动：本次具体做了什么- 范围：影响哪些类/模块/接口- 风险：可能的风险点或兼容说明- 备注：测试说明/回退说明/关联问题单

示例：

AI填单：收敛树字段挂起状态，消除 resolvedSelections 双写

- 背景：pendingAction 职责过重，存在运行态与协议字段混存，导致读写来源不一致- 改动：pendingAction 保留 type/entity/stage/mode/keyword；运行态统一迁移至 EntitySelectionState- 范围：SpecialWorkersSelectionHandlerV2、GenericDropdownHandlerV2、AiPromptContextBuilderV2- 风险：涉及 follow-up 链路，需重点关注树字段继续追问、翻页、未找到后补充场景- 备注：本次未做整文件回填，保持原文件编码与 BOM 不变

5. 标题命名规则

推荐标题结构：

[模块/主题]： [动作] + [对象/目标]

常用动作词：

  • 修复
  • 收敛
  • 拆分
  • 重构
  • 清理
  • 补充
  • 优化
  • 统一
  • 校正
  • 兼容
  • 下沉
  • 抽取

常用标题模板：

  • 模块：修复xxx问题
  • 模块：优化xxx逻辑
  • 模块：重构xxx链路
  • 模块：统一xxx状态模型
  • 模块：清理xxx冗余逻辑
  • 模块：补充xxx校验
  • 模块：拆分xxx职责

示例：

  • AI填单：统一树字段挂起状态读取来源
  • AI填单：拆分 pendingAction 与 EntitySelectionState 职责
  • 日计划：修复人员字段回显与实际保存不一致问题
  • 巡检：补充设备查询为空时的兜底提示

6. 不同类型提交的写法建议

6.1 缺陷修复

模板：

模块：修复[现象/问题]

示例：

  • AI填单：修复树字段人员未找到后 follow-up 串链问题
  • 登录：修复 token 失效后页面未跳转登录页问题

建议补充：

  • 问题出现条件
  • 根因
  • 修复点

6.2 重构优化

模板：

模块：重构/收敛/统一[对象]

示例：

  • AI填单：收敛选择挂起状态来源，拆分 pendingAction 与运行态
  • 设备监测：统一查询参数封装方式

建议补充：

  • 为什么重构
  • 旧设计问题是什么
  • 新结构如何划分

6.3 配置调整

模板：

模块：调整[环境/配置项]

示例：

  • 网关：调整生产环境超时与重试配置
  • Nacos：补充AI填单相关配置项

建议补充：

  • 环境范围
  • 生效对象
  • 是否需要联动发布

6.4 文档提交

模板：

文档：新增/更新[主题]

示例：

  • 文档：新增 SVN 提交规范
  • 文档：更新 TreePending 状态设计说明

6.5 测试/脚本提交

模板：

测试/脚本：补充/修复[目标]

示例：

  • 测试：补充 AI 树字段 follow-up 场景清单
  • 脚本：修复部署脚本路径判断问题

7. 推荐与不推荐示例

7.1 推荐示例

示例一：单点 bug 修复

AI填单：修复树字段翻页后候选快照丢失

- 原因：翻页时候选来源依赖 pendingAction 快照，状态清理后数据不稳定- 改动：候选快照统一改为读取 EntitySelectionState- 影响：树字段人员/单位选择翻页链路

示例二：状态重构

AI填单：收敛选择挂起状态来源，拆分 pendingAction 与运行态

- 原因：pendingAction 同时承担协议和运行态，存在双写、漏写、误清理风险- 改动：运行态迁移至 EntitySelectionState，pendingAction 收敛为协议信封- 影响：通用下拉、树字段选择、AI follow-up prompt 上下文

示例三：配置类改动

网关：补充AI接口超时配置

- 原因：AI 请求高峰期偶发超时- 改动：增加接口超时与重试配置- 影响：网关转发 AI 服务链路

7.2 不推荐示例

  • 修改
  • 继续优化
  • 改一下bug
  • 提交代码
  • 最新版本
  • 功能完成
  • 测试一下

问题在于：

  • 看不出模块
  • 看不出问题
  • 看不出改动范围
  • 无法支持追溯

8. 提交粒度要求

8.1 允许的粒度

推荐一次提交只覆盖以下之一：

  • 一个明确 bug
  • 一个明确需求点
  • 一个明确重构主题
  • 一次独立配置调整
  • 一份独立文档补充

8.2 不推荐的粒度

不建议把以下内容混在一起：

  • bug 修复 + 样式调整
  • 功能开发 + 大量格式化
  • 重构 + 无关文档整理
  • 配置变更 + 逻辑改造 + SQL 变更

如果确实必须一起提交，提交说明中必须明确列出多个子项。

9. 推荐提交前检查项

提交前建议自查：

  • 本次提交是否只有一个主题
  • 标题是否脱离上下文也能看懂
  • 是否说明了“为什么改”
  • 是否标明了影响范围
  • 是否混入了无关文件
  • 是否包含调试日志、临时代码、注释掉的大段废弃代码
  • 是否确认文件编码/BOM 未被误改
  • 是否避免了对老文件做整文件回填式覆盖

10. svn commit -m 推荐模板

10.1 简版模板

svn commit -m "模块：改动目的"

示例：

svn commit -m "AI填单：修复树字段人员未找到后续接错误"

10.2 标准模板

svn commit -m "模块：改动目的
- 原因：...
- 改动：...
- 影响：..."

示例：

svn commit -m "AI填单：收敛选择挂起状态来源，拆分 pendingAction 与运行态
- 原因：pendingAction 同时承担协议和运行态，存在双写和误清理风险
- 改动：运行态统一迁移到 EntitySelectionState，pendingAction 保留协议信封字段
- 影响：通用下拉、树字段选择、AI follow-up prompt 上下文链路"

10.3 完整模板

svn commit -m "模块：改动目的
- 背景：...
- 改动：...
- 范围：...
- 风险：...
- 备注：..."

11. 本项目推荐风格

结合本项目当前开发内容，推荐默认采用以下风格：

标题格式

业务模块：改动目的

常见业务模块建议：

  • AI填单
  • 日计划
  • 周计划
  • 巡检
  • 设备监测
  • 网关
  • 认证
  • 文档

正文格式

  • 原因
  • 改动
  • 影响

这是当前项目最容易执行、也最容易保持统一的形式。

12. 推荐落地要求

建议团队后续统一执行以下规则：

  1. 禁止使用“修改、优化、提交一下、最新版本”这类无意义标题
  2. 除极小改动外，统一使用至少 3 行说明：原因 / 改动 / 影响
  3. 重构类提交必须明确写出旧问题和新边界
  4. 涉及多模块时，正文必须写影响范围
  5. 提交前必须检查是否误改文件编码、BOM、换行风格

13. 建议的团队示例库

后续可以在团队内部持续沉淀“优秀提交样例”，按类型归档：

  • bug 修复类样例
  • 重构优化类样例
  • 配置变更类样例
  • 文档类样例
  • 联调/兼容类样例

建议每月复盘一次，把好的提交说明补充进来，逐步形成团队自己的提交语言风格。

14. 当前场景推荐提交文案

本次改动推荐使用：

标题

AI填单：收敛选择挂起状态来源，拆分 pendingAction 与运行态

标准版

svn commit -m "AI填单：收敛选择挂起状态来源，拆分 pendingAction 与运行态
- 原因：pendingAction 同时承担协议信封与运行态快照，存在双写、漏写、误清理风险
- 改动：通用下拉与树字段选择链路统一将运行态收敛到 EntitySelectionState，pendingAction 仅保留协议字段
- 影响：GenericDropdownHandlerV2、SpecialWorkersSelectionHandlerV2、AiPromptContextBuilderV2 follow-up 链路"

完整版

svn commit -m "AI填单：收敛选择挂起状态来源，拆分 pendingAction 与运行态
- 背景：选择挂起链路存在 pendingAction 与 EntitySelectionState 双状态并存，读写来源不一致
- 改动：resolvedSelections、候选快照、树 follow-up 运行态统一迁移到 EntitySelectionState；pendingAction 收敛为 type/entity/stage/mode/keyword 等协议字段
- 范围：GenericDropdownHandlerV2、SpecialWorkersSelectionHandlerV2、AiPromptContextBuilderV2、TreeDropdownFieldConfigV2
- 风险：重点关注树字段 follow-up、翻页、未找到后继续补充等场景
- 备注：本次未对老文件做整文件回填，保持原文件编码与 BOM 不变"