whale-town-end/docs/development/git_commit_guide.md

Git 提交规范

本文档定义了项目的 Git 提交信息格式规范，以保持提交历史的清晰和一致性。

提交格式

<类型>：<简短描述>

[可选的详细描述]

[可选的注释或关联 Issue]

提交类型

主要类型

类型	说明	示例
init	项目初始化	init：项目初始化，搭建Godot文件结构
feat	新增功能	feat：添加角色移动系统
fix	修复 Bug	fix：修复角色跳跃时的碰撞检测问题
docs	文档更新	docs：更新 README 中的安装说明
style	代码格式调整（不影响功能）	style：统一代码缩进格式
refactor	代码重构（不新增功能也不修复 Bug）	refactor：重构敌人 AI 逻辑
perf	性能优化	perf：优化场景加载速度
test	添加或修改测试	test：添加角色控制器单元测试
chore	构建过程或辅助工具的变动	chore：更新 .gitignore 文件
revert	回滚之前的提交	revert：回滚 feat：添加角色移动系统

后端开发特定类型

类型	说明	示例
api	API 接口相关	api：添加玩家信息查询接口
db	数据库相关	db：创建房间表结构
config	配置文件相关	config：添加数据库连接配置
middleware	中间件相关	middleware：添加请求日志中间件
websocket	WebSocket 相关	websocket：实现游戏状态实时推送
auth	认证授权相关	auth：实现 JWT 身份验证
dto	数据传输对象相关	dto：添加创建房间的 DTO
service	服务层相关	service：实现玩家匹配逻辑

提交示例

基础示例

# 项目初始化
git commit -m "init：项目初始化，搭建 NestJS 项目结构"

# 新增功能
git commit -m "feat：实现玩家注册和登录功能"

# 修复问题
git commit -m "fix：修复房间加入时的并发问题"

# 文档更新
git commit -m "docs：添加 Git 提交规范文档"

带详细描述的示例

git commit -m "feat：添加房间系统

- 实现房间创建和加入功能
- 支持多人房间管理
- 添加房间状态同步机制

关联 Issue #12"

后端开发示例

# API 接口
git commit -m "api：添加玩家信息查询接口"

# 数据库
git commit -m "db：创建玩家和房间表结构"

# WebSocket
git commit -m "websocket：实现玩家位置实时同步"

# 中间件
git commit -m "middleware：添加请求日志和错误处理中间件"

# 认证授权
git commit -m "auth：实现 JWT 身份验证机制"

# DTO
git commit -m "dto：添加创建房间的数据验证"

# 服务层
git commit -m "service：实现玩家匹配算法"

# 配置
git commit -m "config：添加 Redis 缓存配置"

重构和优化示例

# 代码重构
git commit -m "refactor：重构房间管理服务逻辑"

# 性能优化
git commit -m "perf：优化数据库查询性能"

# 代码格式
git commit -m "style：统一 TypeScript 代码风格"

多类型改动的处理

问题场景

有时一次开发工作可能同时包含多种类型的改动，例如：

• 既修复了 Bug，又添加了新功能
• 既重构了代码，又优化了性能
• 既更新了场景，又修改了脚本

推荐做法：拆分提交（强烈推荐）⭐

原则：一次提交只做一件事，保持提交历史清晰

# ❌ 不推荐：混合提交
git commit -m "fix + feat：修复房间 Bug 并添加踢人功能"

# ✅ 推荐：拆分成两次提交
git add src/service/room_service.ts  # 只添加修复 Bug 的部分
git commit -m "fix：修复房间加入时的并发问题"

git add src/service/room_service.ts  # 添加新功能的部分
git commit -m "feat：实现房间踢人功能"

拆分提交的优势

1. 清晰的历史记录：每次提交目的明确，便于回溯
2. 便于代码审查：审查者可以分别查看不同类型的改动
3. 灵活的回滚：可以单独回滚某个功能或修复，而不影响其他改动
4. 更好的协作：团队成员能快速理解每次提交的意图
5. 自动化工具友好：CI/CD 和版本管理工具能更好地处理

如何拆分提交

方法一：使用 git add -p（交互式暂存）

# 交互式选择要暂存的代码块
git add -p src/service/room_service.ts

# 选择修复 Bug 的部分，提交
git commit -m "fix：修复房间加入时的并发问题"

# 暂存剩余的新功能代码
git add src/service/room_service.ts
git commit -m "feat：实现房间踢人功能"

方法二：分步开发和提交

# 第一步：先完成并提交 Bug 修复
# 修改代码...
git add src/service/room_service.ts
git commit -m "fix：修复房间加入时的并发问题"

# 第二步：再开发并提交新功能
# 继续修改代码...
git add src/service/room_service.ts
git commit -m "feat：实现房间踢人功能"

方法三：使用临时分支

# 创建临时分支保存当前工作
git stash

# 只恢复修复 Bug 的部分并提交
git stash pop
# 手动撤销新功能代码，只保留 Bug 修复
git add src/service/room_service.ts
git commit -m "fix：修复房间加入时的并发问题"

# 恢复新功能代码并提交
# 重新添加新功能代码...
git add src/service/room_service.ts
git commit -m "feat：实现房间踢人功能"

特殊情况：确实无法拆分时

如果改动确实紧密耦合、无法拆分（这种情况应该很少见），可以使用以下方式：

方式一：选择主要类型 + 详细描述（推荐）

git commit -m "feat：实现房间匹配系统

- 添加自动匹配的核心逻辑
- 修复原有房间系统的并发问题
- 优化匹配算法的性能

本次提交包含了功能开发和 Bug 修复，因为匹配系统的实现
依赖于修复原有房间系统的并发问题。"

方式二：使用多行描述分别说明

git commit -m "feat：重构并优化房间管理系统

功能改进：
- 实现新的房间状态机
- 添加房间自动回收功能

Bug 修复：
- 修复房间满员时的加入问题
- 修复房间解散时的通知问题

性能优化：
- 减少数据库查询频率
- 优化房间列表缓存策略"

什么时候应该拆分？

情况	是否拆分	原因
修复 Bug + 添加新功能	✅ 应该拆分	两个独立的逻辑改动
重构代码 + 性能优化	✅ 应该拆分	目的不同，影响范围不同
添加 API + 编写服务层	✅ 应该拆分	不同层次的代码改动
修复 Bug + 添加该 Bug 的测试	❌ 可以合并	测试是修复的一部分
重构 + 重构后必需的修复	❌ 可以合并	修复是重构的直接结果
添加功能 + 更新相关文档	⚠️ 视情况而定	简单文档可合并，复杂文档应拆分

注意事项

1. 使用中文冒号：类型后使用中文冒号 ： 而非英文冒号 :
2. 简短明确：描述应简洁明了，一般不超过 50 个字符
3. 动词开头：描述部分使用动词开头，如"添加"、"修复"、"更新"等
4. 一次提交一个改动：每次提交应该只包含一个逻辑改动（最重要的原则）⭐
5. 详细描述：对于复杂的改动，应该添加详细描述说明改动的原因和影响
6. 避免混合类型：不要在一次提交中混合多种类型的改动（如 fix + feat）
7. 先提交修复，再提交功能：如果必须在同一开发周期内完成，优先提交 Bug 修复
8. 使用 git add -p：善用交互式暂存来精确控制每次提交的内容
9. 提交前自查：问自己"这次提交是否只做了一件事？"
10. 保持提交原子性：每次提交都应该是完整的、可独立运行的改动

分支命名规范

# 功能分支
feature/player-system
feature/room-matching

# 修复分支
fix/room-concurrency
fix/websocket-leak

# 开发分支
dev
develop

# 发布分支
release/v1.0.0
release/v1.1.0

常见问题 FAQ

Q1: 我同时修复了 3 个小 Bug，应该分 3 次提交吗？

A: 视情况而定：

• 如果是相关的 Bug（同一个系统/模块），可以合并为一次提交
• 如果是不相关的 Bug（不同系统/模块），应该分别提交

# ✅ 相关 Bug 可以合并
git commit -m "fix：修复房间系统的多个问题

- 修复房间满员时的加入问题
- 修复房间解散时的通知问题
- 修复房间列表的分页错误"

# ✅ 不相关 Bug 应该拆分
git commit -m "fix：修复房间加入时的并发问题"
git commit -m "fix：修复玩家信息查询的权限问题"
git commit -m "fix：修复 WebSocket 连接的内存泄漏"

Q2: 我在开发新功能时发现了 Bug，应该怎么办？

A: 推荐流程：

1. 暂存当前新功能的代码（git stash）
2. 修复 Bug 并提交
3. 恢复新功能代码继续开发
4. 完成后提交新功能

# 保存当前工作
git stash save "WIP: 开发房间匹配功能"

# 修复 Bug
git add src/service/room_service.ts
git commit -m "fix：修复房间加入时的并发问题"

# 恢复工作并继续开发
git stash pop
# 继续开发...
git commit -m "feat：实现房间自动匹配功能"

Q3: 重构代码时顺便优化了性能，算一次提交吗？

A: 应该拆分：

• 重构（refactor）：改变代码结构但不改变行为
• 优化（perf）：改善性能表现

# ✅ 拆分提交
git commit -m "refactor：重构房间管理服务逻辑"
git commit -m "perf：优化房间列表查询性能"

Q4: 我应该多久提交一次？

A: 遵循以下原则：

• ✅ 完成一个完整的逻辑单元就提交
• ✅ 代码能够正常运行时提交
• ✅ 下班前提交当天的工作进度
• ❌ 不要等到功能完全完成才提交（可能跨越多天）
• ❌ 不要提交无法运行的代码

Q5: 提交信息写错了怎么办？

A: 使用 git commit --amend 修改最后一次提交：

# 修改最后一次提交信息
git commit --amend -m "fix：修复房间加入时的并发问题"

# 如果已经推送到远程，需要强制推送（谨慎使用）
git push --force-with-lease

⚠️ 注意：只修改未推送或未被他人使用的提交！

工具推荐

• Commitizen: 交互式提交信息生成工具
• Git Hooks: 使用 pre-commit 钩子自动检查提交格式
• Conventional Commits: 遵循约定式提交规范
• Git GUI 工具: GitKraken、SourceTree 等支持可视化暂存部分代码

总结

记住这些核心原则：

1. ⭐ 一次提交只做一件事 - 最重要的原则
2. 🔀 能拆分就拆分 - 保持提交历史清晰
3. 🎯 提交要有意义 - 每次提交都应该是完整的改动
4. 📝 描述要清晰 - 让别人（和未来的自己）能快速理解
5. 🚫 避免混合类型 - 不要 fix + feat 混在一起

好的提交习惯 = 清晰的项目历史 = 高效的团队协作