docs: Enforce English-only commit messages to prevent encoding issues
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:
@@ -65,6 +65,34 @@ git remote -v
|
||||
|
||||
## 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 主题
|
||||
|
||||
**✅ 推荐：**
|
||||
**✅ 推荐（英文）：**
|
||||
```
|
||||
feat(asl): 实现标题摘要初筛功能
|
||||
fix(frontend): 修复 AgentChatPage conversation 数据提取问题
|
||||
docs: 添加 Day 23-24 工作总结
|
||||
refactor(backend): 优化数据库连接池配置
|
||||
feat(asl): Implement title and abstract screening
|
||||
fix(frontend): Fix AgentChatPage conversation data extraction issue
|
||||
docs: Add Day 23-24 work summary
|
||||
refactor(backend): Optimize database connection pool configuration
|
||||
```
|
||||
|
||||
**❌ 避免：**
|
||||
```
|
||||
更新代码 # 太笼统
|
||||
更新代码 # 中文（会乱码）
|
||||
fix bug # 没有说明具体问题
|
||||
修复了一些问题 # 信息不足
|
||||
修复了一些问题 # 中文（会乱码）+ 信息不足
|
||||
feat: add feature # 没有指明模块和具体功能
|
||||
update code # 太笼统
|
||||
```
|
||||
|
||||
**规则：**
|
||||
- ✅ 使用祈使句（"添加" 而不是 "添加了"）
|
||||
- ⭐ **必须使用英文**（避免中文乱码）
|
||||
- ✅ 使用祈使句（"Add" 而不是 "Added"）
|
||||
- ✅ 首字母小写
|
||||
- ✅ 不要以句号结尾
|
||||
- ✅ 简洁明了（≤50字符）
|
||||
- ✅ 优先使用英文（避免中文乱码）
|
||||
|
||||
### Body 详细描述
|
||||
|
||||
**可选，用于说明：**
|
||||
- 为什么做这个修改？
|
||||
- 修改了什么？
|
||||
- 有什么影响？
|
||||
- Why: 为什么做这个修改？
|
||||
- What: 修改了什么？
|
||||
- Impact: 有什么影响？
|
||||
|
||||
**示例：**
|
||||
**示例（必须使用英文）：**
|
||||
```
|
||||
feat(asl): 实现标题摘要初筛功能
|
||||
feat(asl): Implement title and abstract screening
|
||||
|
||||
完成以下功能：
|
||||
- 添加 CSV 文件导入
|
||||
- 实现双模型 AI 判断（Qwen + DeepSeek）
|
||||
- 添加 PICO 配置功能
|
||||
- 实现批量处理和进度显示
|
||||
Completed features:
|
||||
- Add CSV file import
|
||||
- Implement dual-model AI judgment (Qwen + DeepSeek)
|
||||
- Add PICO configuration
|
||||
- Implement batch processing and progress display
|
||||
|
||||
技术细节：
|
||||
- 使用 Papa Parse 解析 CSV
|
||||
- 集成 Dify API 进行 AI 判断
|
||||
- 使用 Ant Design Upload 组件
|
||||
Technical details:
|
||||
- Use Papa Parse for CSV parsing
|
||||
- Integrate Dify API for AI judgment
|
||||
- Use Ant Design Upload component
|
||||
```
|
||||
|
||||
### Footer 脚注
|
||||
|
||||
**可选，用于：**
|
||||
- 关闭 Issue：`Closes #123`
|
||||
- 不兼容变更：`BREAKING CHANGE: 说明`
|
||||
- 不兼容变更：`BREAKING CHANGE: Description`
|
||||
- 关联 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
|
||||
Refs #456
|
||||
@@ -182,35 +211,36 @@ Refs #456
|
||||
|
||||
### 完整示例
|
||||
|
||||
**示例 1：新功能**
|
||||
**示例 1：新功能（必须使用英文）**
|
||||
```
|
||||
feat(asl): 实现标题摘要初筛功能
|
||||
feat(asl): Implement title and abstract screening
|
||||
|
||||
- 添加 CSV 文件导入
|
||||
- 实现双模型 AI 判断
|
||||
- 添加 PICO 配置功能
|
||||
Features:
|
||||
- Add CSV file import
|
||||
- Implement dual-model AI judgment
|
||||
- Add PICO configuration
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
**示例 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
|
||||
# 每改一个文件就提交一次
|
||||
git commit -m "fix: 修复文件A"
|
||||
git commit -m "fix: 修复文件B"
|
||||
git commit -m "fix: 修复文件C"
|
||||
git commit -m "docs: 更新文档"
|
||||
git commit -m "fix: Fix file A"
|
||||
git commit -m "fix: Fix file B"
|
||||
git commit -m "fix: Fix file C"
|
||||
git commit -m "docs: Update docs"
|
||||
# 结果：产生大量碎片化提交，污染 Git 历史
|
||||
```
|
||||
|
||||
**✅ 正确做法：**
|
||||
**✅ 正确做法（必须使用英文）：**
|
||||
```bash
|
||||
# 一天工作结束后，统一提交
|
||||
git add .
|
||||
git commit -m "feat(asl): 完成标题摘要初筛功能
|
||||
git commit -m "feat(asl): Implement title and abstract screening
|
||||
|
||||
- 实现Excel解析逻辑
|
||||
- 添加LLM异步任务处理
|
||||
- 完善存储服务调用
|
||||
- 更新相关文档
|
||||
Features:
|
||||
- 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
|
||||
# 一天工作结束，完成了 ASL 模块的标题摘要初筛功能
|
||||
# Completed ASL module title and abstract screening at end of day
|
||||
git add backend/src/modules/asl/
|
||||
git add docs/03-业务模块/ASL-AI智能文献/
|
||||
git commit -m "feat(asl): 完成标题摘要初筛功能
|
||||
git commit -m "feat(asl): Implement title and abstract screening
|
||||
|
||||
- 实现Excel解析和验证
|
||||
- 添加LLM异步任务处理
|
||||
- 集成平台基础设施（storage/logger/jobQueue）
|
||||
- 完善API和数据库Schema
|
||||
- 更新开发文档
|
||||
Features:
|
||||
- Implement Excel parsing and validation
|
||||
- Add LLM async task processing
|
||||
- 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
|
||||
# 修复了健康检查路由冲突问题并验证通过
|
||||
# Fixed health check route conflict and verified
|
||||
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 路由在多处注册导致冲突
|
||||
解决：统一在 registerHealthRoutes 中注册
|
||||
Problem: /health route registered in multiple places causing conflicts
|
||||
Solution: Unified registration in registerHealthRoutes
|
||||
|
||||
Fixes: FastifyError Method 'GET' already declared for route '/health'
|
||||
Tested: 服务启动成功，三个端点均可访问"
|
||||
Tested: Service started successfully, all three endpoints accessible"
|
||||
```
|
||||
|
||||
**场景 3：架构升级**
|
||||
**场景 3：架构升级（必须使用英文）**
|
||||
```bash
|
||||
# 完成平台基础设施实施并验证
|
||||
# Completed platform infrastructure implementation and verification
|
||||
git add backend/src/common/ backend/src/config/
|
||||
git add docs/
|
||||
git commit -m "feat(platform): 实施平台基础设施（8个核心模块）
|
||||
git commit -m "feat(platform): Implement platform infrastructure (8 core modules)
|
||||
|
||||
完成内容：
|
||||
- 存储服务（LocalAdapter + OSSAdapter预留）
|
||||
- 日志系统（Winston + JSON格式）
|
||||
- 缓存服务（Memory + Redis预留）
|
||||
- 异步任务（MemoryQueue + DatabaseQueue预留）
|
||||
- 健康检查（liveness + readiness）
|
||||
- 监控指标（数据库/内存/API）
|
||||
- 数据库连接池（防止Serverless超限）
|
||||
- 环境配置管理
|
||||
Completed:
|
||||
- Storage service (LocalAdapter + OSSAdapter reserved)
|
||||
- Logging system (Winston + JSON format)
|
||||
- Cache service (Memory + Redis reserved)
|
||||
- Async tasks (MemoryQueue + DatabaseQueue reserved)
|
||||
- Health checks (liveness + readiness)
|
||||
- Monitoring metrics (DB/memory/API)
|
||||
- Database connection pool (prevent Serverless limit)
|
||||
- Environment configuration
|
||||
|
||||
设计原则：适配器模式实现零代码环境切换
|
||||
实施时间：2.5天（20小时）
|
||||
验收状态：本地开发环境验证通过
|
||||
Design principle: Adapter pattern for zero-code env switching
|
||||
Implementation: 2.5 days (20 hours)
|
||||
Status: Local dev environment verified
|
||||
|
||||
Related: #Platform-Infrastructure"
|
||||
```
|
||||
@@ -585,16 +617,21 @@ $env:LESSCHARSET = 'utf-8'
|
||||
- `.editorconfig` - 统一编辑器编码配置（UTF-8）
|
||||
- `.gitattributes` - 统一 Git 文件编码处理
|
||||
|
||||
**4. 最佳实践：使用英文提交信息** ⭐ 推荐
|
||||
**4. 强制要求：必须使用英文提交信息** ⭐⭐⭐ 必须
|
||||
|
||||
```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 规范和中文乱码解决方案
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user