提交信息准备指南
Commit Message Preparation
AI语言模型的Git提交指南。遵循常规提交规范，简洁准确，避免华丽措辞。
detail.target_platforms
ChatGPTClaudeGemini
# 适用于 AI 语言模型的 Git 提交指南
## 核心原则
1. **遵循 Conventional Commits** (https://www.conventionalcommits.org/)
2. **简洁精确** - 不使用华丽的辞藻、最高级或不必要的形容词
3. **关注“什么”改变了，而不是“如何”工作** - 描述变更，而非实现细节
4. **每次提交一个逻辑变更** - 将相关但独立的变更拆分为单独的提交
5. **使用祈使语气** - “Add feature”而非“Added feature”或“Adds feature”
6. **始终包含正文** - 绝不使用仅有主题的提交
## 提交消息结构
```
<type>(<scope>): <subject>
<body>
<footer>
```
### 类型 (必填)
- `feat`: 新功能
- `fix`: Bug 修复
- `refactor`: 既不修复 bug 也不添加功能的代码更改
- `perf`: 性能改进
- `style`: 代码风格更改（格式化、缺少分号等）
- `test`: 添加或更新测试
- `docs`: 文档更改
- `build`: 构建系统或外部依赖（npm, gradle, Xcode, SPM）
- `ci`: CI/CD 流水线更改
- `chore`: 日常任务（gitignore, 配置文件, 维护）
- `revert`: 撤销之前的提交
### 范围 (可选但推荐)
指示变更的区域：`auth`, `ui`, `api`, `db`, `i18n`, `analytics` 等。
### 主题 (必填)
- **最多 50 个字符**
- **首字母小写** (除非是专有名词)
- **末尾不加句号**
- **祈使语气**：“add”而非“added”或“adds”
- **具体明确**：“add email validation”而非“add validation”
### 正文 (必填)
- **始终包含正文** - 最少 1 句话
- **解释 WHAT 改变了以及 WHY** - 提供上下文
- **行宽限制在 72 个字符**
- **与主题行之间用空行分隔**
- **多项更改使用项目符号**（使用 `-` 或 `*`）
- **如果适用，引用问题编号**
- **提及相关的特定类/函数/文件**
### 脚注（可选）
- **破坏性变更**：`BREAKING CHANGE: <描述>`
- **问题引用**：`Closes #123`，`Fixes #456`
- **共同作者**：`Co-Authored-By: Name <email>`
## 禁用词和短语
**绝不使用这些词**（它们模糊、主观或夸大）：
❌ Comprehensive（全面的）
❌ Robust（健壮的）
❌ Enhanced（增强的）
❌ Improved（改进的）（除非你指明改进了什么指标）
❌ Optimized（优化的）（除非你指明优化了什么指标）
❌ Better（更好的）
❌ Awesome（棒极了的）
❌ Great（很棒的）
❌ Amazing（惊人的）
❌ Powerful（强大的）
❌ Seamless（无缝的）
❌ Elegant（优雅的）
❌ Clean（整洁的）
❌ Modern（现代的）
❌ Advanced（高级的）
## 好坏示例
### ❌ 差（无正文）
```
feat(auth): add email/password login
```
**问题：**
- 无正文
- 未解释实际实现了什么
### ❌ 差（正文模糊）
```
feat: Add awesome new login feature
This commit adds a powerful new login system with robust authentication
and enhanced security features. The implementation is clean and modern.
```
**问题：**
- 主观形容词（awesome, powerful, robust, enhanced, clean, modern）
- 未指明添加了什么
- 正文描述的是质量，而非功能
### ✅ 好
```
feat(auth): add email/password login with Firebase
Implement login flow using Firebase Authentication. Users can now sign in
with email and password. Includes client-side email validation and error
handling for network failures and invalid credentials.
```
**为什么它好：**
- 提到了具体技术 (Firebase)
- 范围明确 (auth)
- 正文描述了添加的功能
- 解释了错误处理涵盖的内容
---
### ❌ 差 (无正文)
```
fix(auth): prevent login button double-tap
```
**问题：**
- 没有正文解释修复内容
### ✅ 好
```
fix(auth): prevent login button double-tap
首次点击后禁用登录按钮，以防止用户快速多次点击时发送重复的身份验证请求。
按钮在身份验证完成或失败后重新启用。
```
**为什么它好：**
- 祈使语气
- 描述了具体问题
- 正文解释了问题和解决方案方法
---
### ❌ 差
```
refactor(auth): extract helper functions
通过提取函数使代码更好、更易维护。
```
**问题：**
- 主观 (更好、更易维护)
- 没有具体说明是哪些函数
### ✅ 好
```
refactor(auth): extract helper functions to static struct methods
将私有函数 randomNonceString 和 sha256 转换为 AppleSignInHelper 结构体的静态方法，
以实现更好的代码组织和命名空间。
```
**为什么它好：**
- 描述了具体更改
- 提到了确切的函数名
- 正文解释了原因和新结构
---
### ❌ 差
```
feat(i18n): add localization
```
**问题：**
- 无正文
- 太模糊
### ✅ 好
```
feat(i18n): add English and Turkish translations for login screen
创建包含登录 UI 元素、警报和身份验证错误的英语和土耳其语翻译的字符串目录。
涵盖 LoginView、LoginViewController 和 AuthService 中所有面向用户的字符串。
```
**为什么它好：**
- 提到了具体语言
- 范围明确 (i18n)
- 正文列出了翻译内容和涉及的文件
---
## 多文件提交指南
### 何时拆分提交
在以下情况下，将更改拆分为单独的提交：
1. **不同的逻辑关注点**
- ✅ 提交 1：添加函数
- ✅ 提交 2：为函数添加测试
2. **不同的范围**
- ✅ 提交 1：`feat(ui): add button component`
- ✅ 提交 2：`feat(api): add endpoint for button action`
3. **不同的类型**
- ✅ 提交 1：`feat(auth): add login form`
- ✅ 提交 2：`refactor(auth): extract validation logic`
### 何时合并提交
在以下情况下，将更改合并到一个提交中：
1. **紧密耦合的更改**
- ✅ 在同一组件中添加函数及其用法
2. **原子性更改**
- ✅ 跨多个文件重构函数名
3. **彼此独立则会破坏**
- ✅ 同时添加接口及其实现
## 文件级提交策略
### 示例：LoginView 更改
如果 LoginView 有 2 个独立的更改：
**更改 1：** 重构堆栈视图结构
**更改 2：** 添加加载指示器
**拆分为 2 个提交：**
```
refactor(ui): extract content stack view as property in login view
Change inline stack view initialization to property-based approach for
better code organization and reusability. Moves stack view definition
from setupUI method to lazy property.
```
```
feat(ui): add loading state with activity indicator to login view
Add loading indicator overlay and setLoading method to disable user
interaction and dim content during authentication. Content alpha reduces
to 0.5 when loading.
```
## 本地化特定指南
### ✅ 良好
```
feat(i18n): add English and Turkish translations
Create String Catalog (Localizable.xcstrings) with English and Turkish
translations for all login screen strings, error messages, and alerts.
```
```
build(i18n): add Turkish localization support
```
将土耳其语添加到项目本地化中，并在 Debug 和 Release 配置的构建设置中启用 String Catalog 生成 (SWIFT_EMIT_LOC_STRINGS)。
```
```
feat(i18n): 本地化登录视图 UI 元素
将 LoginView 中标题、副标题、标签、占位符和按钮标题的硬编码字符串替换为 NSLocalizedString。所有面向用户的文本现在都支持本地化。
```
### ❌ 不好
```
feat: 添加全面的多语言支持
为应用程序添加出色的本地化系统。
```
```
feat: 添加翻译
```
## 破坏性变更
引入破坏性变更时：
```
feat(api): 更改身份验证响应结构
身份验证端点现在在 'data' 字段中返回用户对象，而不是在根级别。这允许在响应中包含额外的元数据。
BREAKING CHANGE: 更新所有 API 消费者以访问 response.data.user，而不是 response.user。
迁移指南：
- 之前：const user = response.user
- 之后：const user = response.data.user
```
## 提交顺序
准备多个提交时，按逻辑顺序排列：
1. **依赖项优先**：先添加库/配置，再使用
2. **基础优先于功能**：模型优先于视图
3. **构建优先于源代码**：构建配置优先于代码更改
4. **工具优先于消费者**：帮助函数优先于使用它们的组件
### 示例顺序：
```
1. build(auth): 添加使用 Apple 登录的授权
添加包含使用 Apple 登录功能的授权文件，以启用 Apple ID 身份验证。
2. feat(auth): 添加 Apple 登录加密帮助函数
添加用于生成随机 nonce 和 SHA256 哈希的实用函数，这是 Apple 登录身份验证流程所必需的。
```
3. feat(auth): 为 AuthService 添加 Apple 登录认证
为 AuthService 协议和实现添加 signInWithApple 方法。
使用带有 idToken 和 nonce 的 OAuthProvider 凭据进行 Firebase 认证。
4. feat(auth): 为登录视图模型添加 Apple 登录流程
在 LoginViewModel 中实现 loginWithApple 方法，以处理带有 idToken、nonce 和 fullName 的 Apple 认证。
5. feat(auth): 实现 Apple 登录授权流程
添加 ASAuthorizationController 委托方法来处理 Apple 登录授权、凭据验证和错误处理。
```
## 特殊情况
### 配置文件
```
chore: 忽略 GoogleService-Info.plist 的版本控制
将 GoogleService-Info.plist 添加到 .gitignore，以防止提交包含 API 密钥的 Firebase 配置。
```
```
build: 将 iOS 部署目标更新到 15.0
将最低 iOS 版本从 14.0 更改为 15.0，以支持认证流程中的 async/await 语法。
```
```
ci: 添加用于测试的 GitHub Actions 工作流
添加工作流以在拉取请求上运行单元测试。在 macOS 最新版上运行，使用 Xcode 15。
```
### 文档
```
docs: 添加 API 认证指南
记录 Firebase 认证设置过程，包括 Google 登录和 Apple 登录的配置步骤。
```
```
docs: 更新 README，包含安装步骤
添加 SPM 依赖安装说明和 Firebase 设置指南。
```
### 重构
```
refactor(auth): 将辅助函数转换为静态结构体方法
将 Apple 登录辅助函数封装在 AppleSignInHelper 结构体中，并使用静态方法，以实现更好的代码组织和命名空间。将 randomNonceString 和 sha256 从私有函数转换为静态方法。
```
```
refactor(ui): 将电子邮件验证提取到单独的方法中
```
将电子邮件验证的正则表达式逻辑从 `loginWithEmail` 方法移至 `isValidEmail` 方法，以提高复用性和可测试性。
```
### 性能
**具体说明改进：**
❌ `perf: optimize login`
✅
```
perf(auth): 将登录请求时间从 2 秒减少到 500 毫秒
为 Firebase 配置添加请求缓存，以避免重复的网络调用。配置现在在首次检索后被缓存。
```
## 正文要求
**正文的最低要求：**
1. **至少 1-2 个完整的句子**
2. **具体描述更改了什么**
3. **解释为什么需要此更改（当不明显时）**
4. **提及受影响的组件/文件（如果相关）**
5. **包含主题中不明显的技术细节**
### 好的正文示例：
```
添加加载指示器覆盖层和 setLoading 方法，以在身份验证期间禁用用户交互并调暗内容。
```
```
更新 signInWithApple 方法以接受 fullName 参数，并使用 appleCredential 在 Firebase 中正确创建用户配置文件。
```
```
在 LoginView 中用 NSLocalizedString 替换硬编码字符串，用于标题、标签、占位符和按钮。所有 UI 文本现在支持英语和土耳其语翻译。
```
### 坏的正文示例：
❌ `Add feature.` (太模糊)
❌ `Updated files.` (没有解释什么)
❌ `Bug fix.` (没有解释哪个 bug)
❌ `Refactoring.` (没有解释重构了什么)
## AI 模型模板
当要求 AI 模型创建提交时：
```
1. 阅读 git diff 以理解所有更改
2. 按逻辑关注点对更改进行分组
3. 按依赖关系排序提交
4. 对于每个提交：
- 选择合适的类型和范围
- 编写具体、简洁的主题（最多 50 个字符）
- 编写详细的正文（最少 1-2 句话，必需）
- 使用祈使语气
- 避免使用禁用词
- 关注 WHAT 改变了以及 WHY
5. 输出格式：
## 提交 [N]
**标题：**
```
type(scope): subject
```
**描述：**
```
正文解释了什么改变了以及为什么。提及受影响的特定
组件、类或方法。提供上下文。
```
**要添加的文件：**
```bash
git add path/to/file
```
```
## 最终清单
在建议提交之前，请验证：
- [ ] 类型正确（feat/fix/refactor/等）
- [ ] 范围具体且有意义
- [ ] 主题是祈使语气
- [ ] 主题 ≤50 个字符
- [ ] **正文存在（必需）**
- [ ] **正文至少有 1-2 个完整的句子**
- [ ] 正文解释了 WHAT 和 WHY
- [ ] 没有使用禁用词
- [ ] 没有主观形容词
- [ ] 具体说明 WHAT 改变了
- [ ] 提及受影响的组件/文件
- [ ] 每个提交一个逻辑更改
- [ ] 文件分组正确
---
## 提交消息示例（完整）
```
feat(auth): add email validation to login form
Implement client-side email validation using regex pattern before sending
authentication request. Validates format matches standard email pattern
(user@domain.ext) and displays error message for invalid inputs. Prevents
unnecessary Firebase API calls for malformed emails.
```
**此提示词的优点：**
- 类型和范围清晰
- 主题明确
- 正文解释了验证的作用
- 正文解释了为什么需要验证
- 提到了好处（防止 API 调用）
- 没有禁用词
- 始终使用祈使语气
---
**请记住：** 一个好的提交信息应该让人们无需查看差异就能理解更改。要具体、简洁、客观，并且始终包含有意义的正文。