Develop/AIclinicalresearch
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Enforce English-only commit messages to prevent encoding issues

Browse Source 
Changes:
- Add prominent warning at the beginning of Commit Message section
- Update all commit message examples to English
- Change 'recommended' to 'mandatory' for English usage
- Update best practices section with stronger requirement
- Update all scenario examples (feature/bugfix/architecture)
- Update version history to v1.1

Reason:
- Chinese characters in commit messages cause garbled text in Windows PowerShell
- No encoding configuration can fully resolve this issue
- English commit messages are standard practice in open source projects

Reference: Fixed commit beb7f7f which had garbled Chinese text
This commit is contained in:
HaHafeng
2025-11-22 22:27:27 +08:00
parent beb7f7f559
commit 08aa3f6c28
1 changed files with 131 additions and 90 deletions
Download Patch File Download Diff File Expand all files Collapse all files

221
docs/04-开发规范/06-Git提交规范.md
View File

@@ -65,6 +65,34 @@ git remote -v
## Commit Message 规范 ## Commit Message 规范
### ⚠️ 重要提示：避免中文乱码
**强制要求：Commit Message 必须使用英文** ⭐⭐⭐
**原因**：
- Windows PowerShell 环境下，Git commit message 中的中文会出现乱码
- 中文乱码会导致提交历史难以阅读，影响团队协作
- 英文 commit message 是国际开源项目的标准实践
**✅ 正确示例：**
```bash
git commit -m "feat(asl): Implement full-text screening core service"
git commit -m "fix(frontend): Fix dropdown menu click issue"
git commit -m "docs: Add development guide for Day 2-3"
```
**❌ 错误示例：**
```bash
git commit -m "feat(asl): 实现全文复筛核心服务" # 会出现乱码
git commit -m "修复下拉菜单问题" # 会出现乱码
```
**例外情况**：
- 文件名和文件内容可以使用中文（Git 能正确处理 UTF-8 编码的文件）
- 仅 commit message 必须使用英文
---
### 📝 格式规范 ### 📝 格式规范
**标准格式：** **标准格式：**
@@ -116,65 +144,66 @@ git remote -v
### Subject 主题 ### Subject 主题
**✅ 推荐：** **✅ 推荐（英文）：**
``` ```
feat(asl): 实现标题摘要初筛功能 feat(asl): Implement title and abstract screening
fix(frontend): 修复 AgentChatPage conversation 数据提取问题 fix(frontend): Fix AgentChatPage conversation data extraction issue
docs: 添加 Day 23-24 工作总结 docs: Add Day 23-24 work summary
refactor(backend): 优化数据库连接池配置 refactor(backend): Optimize database connection pool configuration
``` ```
**❌ 避免：** **❌ 避免：**
``` ```
更新代码 # 太笼统 更新代码 # 中文（会乱码）
fix bug # 没有说明具体问题 fix bug # 没有说明具体问题
修复了一些问题 # 信息不足 修复了一些问题 # 中文（会乱码）+ 信息不足
feat: add feature # 没有指明模块和具体功能 feat: add feature # 没有指明模块和具体功能
update code # 太笼统
``` ```
**规则：** **规则：**
- ✅ 使用祈使句（"添加" 而不是 "添加了"） - ⭐ **必须使用英文**（避免中文乱码）
- ✅ 使用祈使句（"Add" 而不是 "Added"）
- ✅ 首字母小写 - ✅ 首字母小写
- ✅ 不要以句号结尾 - ✅ 不要以句号结尾
- ✅ 简洁明了（≤50字符） - ✅ 简洁明了（≤50字符）
- ✅ 优先使用英文（避免中文乱码）
### Body 详细描述 ### Body 详细描述
**可选，用于说明：** **可选，用于说明：**
- 为什么做这个修改？ - Why: 为什么做这个修改？
- 修改了什么？ - What: 修改了什么？
- 有什么影响？ - Impact: 有什么影响？
**示例：** **示例（必须使用英文）：**
``` ```
feat(asl): 实现标题摘要初筛功能 feat(asl): Implement title and abstract screening
完成以下功能： Completed features:
- 添加 CSV 文件导入 - Add CSV file import
- 实现双模型 AI 判断（Qwen + DeepSeek） - Implement dual-model AI judgment (Qwen + DeepSeek)
- 添加 PICO 配置功能 - Add PICO configuration
- 实现批量处理和进度显示 - Implement batch processing and progress display
技术细节： Technical details:
- 使用 Papa Parse 解析 CSV - Use Papa Parse for CSV parsing
- 集成 Dify API 进行 AI 判断 - Integrate Dify API for AI judgment
- 使用 Ant Design Upload 组件 - Use Ant Design Upload component
``` ```
### Footer 脚注 ### Footer 脚注
**可选，用于：** **可选，用于：**
- 关闭 Issue：`Closes #123` - 关闭 Issue：`Closes #123`
- 不兼容变更：`BREAKING CHANGE: 说明` - 不兼容变更：`BREAKING CHANGE: Description`
- 关联 Issue：`Refs #456` - 关联 Issue：`Refs #456`
**示例：** **示例（必须使用英文）：**
``` ```
feat(backend): 重构 API 路由结构 feat(backend): Refactor API routing structure
BREAKING CHANGE: API 路由从 /api/xxx 改为 /api/v1/xxx BREAKING CHANGE: API routes changed from /api/xxx to /api/v1/xxx
所有前端调用需要更新路径 All frontend API calls need to be updated
Closes #123 Closes #123
Refs #456 Refs #456
@@ -182,35 +211,36 @@ Refs #456
### 完整示例 ### 完整示例
**示例 1：新功能** **示例 1：新功能（必须使用英文）**
``` ```
feat(asl): 实现标题摘要初筛功能 feat(asl): Implement title and abstract screening
- 添加 CSV 文件导入 Features:
- 实现双模型 AI 判断 - Add CSV file import
- 添加 PICO 配置功能 - Implement dual-model AI judgment
- Add PICO configuration
Closes #123 Closes #123
``` ```
**示例 2：Bug 修复** **示例 2：Bug 修复（必须使用英文）**
``` ```
fix(frontend): 修复 AgentChatPage conversation 数据提取问题 fix(frontend): Fix AgentChatPage conversation data extraction issue
问题：conversation 数据未正确从响应中提取 Problem: Conversation data not correctly extracted from response
解决：修改数据解析逻辑，正确处理嵌套结构 Solution: Modify data parsing logic to handle nested structures
Fixes #234 Fixes #234
``` ```
**示例 3：文档更新** **示例 3：文档更新（必须使用英文）**
``` ```
docs: 添加 Day 23-24 工作总结 docs: Add Day 23-24 work summary
完成内容： Contents:
- 知识库功能开发总结 - Knowledge base development summary
- 遇到的问题与解决方案 - Issues encountered and solutions
- 下一步计划 - Next steps
``` ```
--- ---
@@ -226,25 +256,26 @@ docs: 添加 Day 23-24 工作总结
**❌ 错误做法：** **❌ 错误做法：**
```bash ```bash
# 每改一个文件就提交一次 # 每改一个文件就提交一次
git commit -m "fix: 修复文件A" git commit -m "fix: Fix file A"
git commit -m "fix: 修复文件B" git commit -m "fix: Fix file B"
git commit -m "fix: 修复文件C" git commit -m "fix: Fix file C"
git commit -m "docs: 更新文档" git commit -m "docs: Update docs"
# 结果：产生大量碎片化提交，污染 Git 历史 # 结果：产生大量碎片化提交，污染 Git 历史
``` ```
**✅ 正确做法：** **✅ 正确做法（必须使用英文）：**
```bash ```bash
# 一天工作结束后，统一提交 # 一天工作结束后，统一提交
git add . git add .
git commit -m "feat(asl): 完成标题摘要初筛功能 git commit -m "feat(asl): Implement title and abstract screening
- 实现Excel解析逻辑 Features:
- 添加LLM异步任务处理 - Implement Excel parsing logic
- 完善存储服务调用 - Add LLM async task processing
- 更新相关文档 - Complete storage service integration
- Update related documentation
Tested: 本地验证通过" Tested: Local verification passed"
``` ```
**推荐提交频率：** **推荐提交频率：**
@@ -348,55 +379,56 @@ AI: 收到！现在提交...
### ✅ 推荐的提交场景 ### ✅ 推荐的提交场景
**场景 1：功能开发完成** **场景 1：功能开发完成（必须使用英文）**
```bash ```bash
# 一天工作结束，完成了 ASL 模块的标题摘要初筛功能 # Completed ASL module title and abstract screening at end of day
git add backend/src/modules/asl/ git add backend/src/modules/asl/
git add docs/03-业务模块/ASL-AI智能文献/ git add docs/03-业务模块/ASL-AI智能文献/
git commit -m "feat(asl): 完成标题摘要初筛功能 git commit -m "feat(asl): Implement title and abstract screening
- 实现Excel解析和验证 Features:
- 添加LLM异步任务处理 - Implement Excel parsing and validation
- 集成平台基础设施（storage/logger/jobQueue） - Add LLM async task processing
- 完善API和数据库Schema - Integrate platform infrastructure (storage/logger/jobQueue)
- 更新开发文档 - Complete API and database schema
- Update development documentation
Tested: 本地测试通过，功能验证完成" Tested: Local tests passed, functionality verified"
``` ```
**场景 2：Bug 修复** **场景 2：Bug 修复（必须使用英文）**
```bash ```bash
# 修复了健康检查路由冲突问题并验证通过 # Fixed health check route conflict and verified
git add backend/src/index.ts backend/src/common/health/ git add backend/src/index.ts backend/src/common/health/
git commit -m "fix(backend): 修复健康检查路由重复注册问题 git commit -m "fix(backend): Fix duplicate health check route registration
问题：/health 路由在多处注册导致冲突 Problem: /health route registered in multiple places causing conflicts
解决：统一在 registerHealthRoutes 中注册 Solution: Unified registration in registerHealthRoutes
Fixes: FastifyError Method 'GET' already declared for route '/health' Fixes: FastifyError Method 'GET' already declared for route '/health'
Tested: 服务启动成功，三个端点均可访问" Tested: Service started successfully, all three endpoints accessible"
``` ```
**场景 3：架构升级** **场景 3：架构升级（必须使用英文）**
```bash ```bash
# 完成平台基础设施实施并验证 # Completed platform infrastructure implementation and verification
git add backend/src/common/ backend/src/config/ git add backend/src/common/ backend/src/config/
git add docs/ git add docs/
git commit -m "feat(platform): 实施平台基础设施（8个核心模块） git commit -m "feat(platform): Implement platform infrastructure (8 core modules)
完成内容： Completed:
- 存储服务（LocalAdapter + OSSAdapter预留） - Storage service (LocalAdapter + OSSAdapter reserved)
- 日志系统（Winston + JSON格式） - Logging system (Winston + JSON format)
- 缓存服务（Memory + Redis预留） - Cache service (Memory + Redis reserved)
- 异步任务（MemoryQueue + DatabaseQueue预留） - Async tasks (MemoryQueue + DatabaseQueue reserved)
- 健康检查（liveness + readiness） - Health checks (liveness + readiness)
- 监控指标（数据库/内存/API） - Monitoring metrics (DB/memory/API)
- 数据库连接池（防止Serverless超限） - Database connection pool (prevent Serverless limit)
- 环境配置管理 - Environment configuration
设计原则：适配器模式实现零代码环境切换 Design principle: Adapter pattern for zero-code env switching
实施时间：2.5天（20小时） Implementation: 2.5 days (20 hours)
验收状态：本地开发环境验证通过 Status: Local dev environment verified
Related: #Platform-Infrastructure" Related: #Platform-Infrastructure"
``` ```
@@ -585,16 +617,21 @@ $env:LESSCHARSET = 'utf-8'
- `.editorconfig` - 统一编辑器编码配置（UTF-8） - `.editorconfig` - 统一编辑器编码配置（UTF-8）
- `.gitattributes` - 统一 Git 文件编码处理 - `.gitattributes` - 统一 Git 文件编码处理
**4. 最佳实践：使用英文提交信息** ⭐ 推荐 **4. 强制要求：必须使用英文提交信息** ⭐⭐⭐ 必须
```bash ```bash
# ✅ 推荐：使用英文 # ✅ 正确：必须使用英文
git commit -m "feat(asl): add screening feature" git commit -m "feat(asl): Add screening feature"
# ⚪ 可选：使用中文（需要正确配置编码） # ❌ 错误：禁止使用中文（会出现乱码）
git commit -m "feat(asl): 添加初筛功能" git commit -m "feat(asl): 添加初筛功能" # 会出现乱码！
``` ```
**原因**：
- Windows PowerShell 环境下中文会乱码
- 无论如何配置编码都无法完全避免乱码问题
- **唯一解决方案：使用英文**
### 🔧 修复历史提交中的中文乱码 ### 🔧 修复历史提交中的中文乱码
**使用修复脚本：** **使用修复脚本：**
@@ -1073,9 +1110,13 @@ git push-current # 推送当前分支
--- ---
**最后更新：** 2025-11-16 **最后更新：** 2025-11-22
**维护人：** 技术架构师 **维护人：** 技术架构师
**版本历史：** **版本历史：**
- v1.1 (2025-11-22): **强制要求 Commit Message 使用英文**，避免中文乱码问题
- 在"Commit Message 规范"开头添加重要提示
- 更新所有示例为英文版本
- 将"优先使用英文"改为"必须使用英文"
- v1.0 (2025-11-16): 初始版本，包含完整的 Git 规范和中文乱码解决方案 - v1.0 (2025-11-16): 初始版本，包含完整的 Git 规范和中文乱码解决方案