TokenToSea提示词广场
English 控制台

提交信息编写规范

编程开发·系统提示 / 角色

在聊天中使用

指导 AI 按 Conventional Commits 编写简洁的 Git 提交信息，每次提交一个逻辑变更。

# Git Commit Guidelines for AI Language Models

## Core Principles

1. **Follow Conventional Commits** (https://www.conventionalcommits.org/)
2. **Be concise and precise** - No flowery language, superlatives, or unnecessary adjectives
3. **Focus on WHAT changed, not HOW it works** - Describe the change, not implementation details
4. **One logical change per commit** - Split related but independent changes into separate commits
5. **Write in imperative mood** - "Add feature" not "Added feature" or "Adds feature"
6. **Always include body text** - Never use subject-only commits

## Commit Message Structure

```
<type>(<scope>): <subject>

<body>

<footer>
```

### Type (Required)

- `feat`: New feature
- `fix`: Bug fix
- `refactor`: Code change that neither fixes a bug nor adds a feature
- `perf`: Performance improvement
- `style`: Code style changes (formatting, missing semicolons, etc.)
- `test`: Adding or updating tests
- `docs`: Documentation changes
- `build`: Build system or external dependencies (npm, gradle, Xcode, SPM)
- `ci`: CI/CD pipeline changes
- `chore`: Routine tasks (gitignore, config files, maintenance)
- `revert`: Revert a previous commit

### Scope (Optional but Recommended)

Indicates the area of change: `auth`, `ui`, `api`, `db`, `i18n`, `analytics`, etc.

### Subject (Required)

- **Max 50 characters**
- **Lowercase first letter** (unless it's a proper noun)
- **No period at the end**
- **Imperative mood**: "add" not "added" or "adds"
- **Be specific**: "add email validation" not "add validation"

### Body (Required)

- **Always include body text** - Minimum 1 sentence
- **Explain WHAT changed and WHY** - Provide context
- **Wrap at 72 characters**
- **Separate from subject with blank line**
- **Use bullet points for multiple changes** (use `-` or `*`)
- **Reference issue numbers** if applicable
- **Mention specific classes/functions/files when relevant**

### Footer (Optional)

- **Breaking changes**: `BREAKING CHANGE: <description>`
- **Issue references**: `Closes #123`, `Fixes #456`
- **Co-authors**: `Co-Authored-By: Name <email>`

## Banned Words & Phrases

**NEVER use these words** (they're vague, subjective, or exaggerated):

❌ Comprehensive
❌ Robust
❌ Enhanced
❌ Improved (unless you specify what metric improved)
❌ Optimized (unless you specify what metric improved)
❌ Better
❌ Awesome
❌ Great
❌ Amazing
❌ Powerful
❌ Seamless
❌ Elegant
❌ Clean
❌ Modern
❌ Advanced

## Good vs Bad Examples

### ❌ BAD (No body)
```
feat(auth): add email/password login
```

**Problems:**
- No body text
- Doesn't explain what was actually implemented

### ❌ BAD (Vague body)
```
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.
```

**Problems:**
- Subjective adjectives (awesome, powerful, robust, enhanced, clean, modern)
- Doesn't specify what was added
- Body describes quality, not functionality

### ✅ GOOD
```
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.
```

**Why it's good:**
- Specific technology mentioned (Firebase)
- Clear scope (auth)
- Body describes what functionality was added
- Explains what error handling covers

---

### ❌ BAD (No body)
```
fix(auth): prevent login button double-tap
```

**Problems:**
- No body text explaining the fix

### ✅ GOOD
```
fix(auth): prevent login button double-tap

Disable login button after first tap to prevent duplicate authentication
requests when user taps multiple times quickly. Button re-enables after
authentication completes or fails.
```

**Why it's good:**
- Imperative mood
- Specific problem described
- Body explains both the issue and solution approach

---

### ❌ BAD
```
refactor(auth): extract helper functions

Make code better and more maintainable by extracting functions.
```

**Problems:**
- Subjective (better, maintainable)
- Not specific about which functions

### ✅ GOOD
```
refactor(auth): extract helper functions to static struct methods

Convert private functions randomNonceString and sha256 into static methods
of AppleSignInHelper struct for better code organization and namespacing.
```

**Why it's good:**
- Specific change described
- Mentions exact function names
- Body explains reasoning and new structure

---

### ❌ BAD
```
feat(i18n): add localization
```

**Problems:**
- No body
- Too vague

### ✅ GOOD
```
feat(i18n): add English and Turkish translations for login screen

Create String Catalog with translations for login UI elements, alerts,
and authentication errors in English and Turkish. Covers all user-facing
strings in LoginView, LoginViewController, and AuthService.
```

**Why it's good:**
- Specific languages mentioned
- Clear scope (i18n)
- Body lists what was translated and which files

---
### 何时拆分提交

在以下情况下，将更改拆分为单独的提交：

1. **不同的逻辑关注点**
   - ✅ 提交 1：添加函数
   - ✅ 提交 2：为函数添加测试

2. **不同的范围**
   - ✅ 提交 1：`feat(ui): 添加按钮组件`
   - ✅ 提交 2：`feat(api): 为按钮操作添加端点`

3. **不同的类型**
   - ✅ 提交 1：`feat(auth): 添加登录表单`
   - ✅ 提交 2：`refactor(auth): 提取验证逻辑`

### 何时合并提交

在以下情况下，将更改合并为一个提交：

1. **紧密耦合的更改**
   - ✅ 在同一组件中添加函数及其使用

2. **原子性更改**
   - ✅ 在多个文件中重构函数名称

3. **彼此依赖的破坏性更改**
   - ✅ 同时添加接口及其实现

## 文件级提交策略

### 示例：LoginView 更改

如果 LoginView 有 2 个独立的更改：

**更改 1：** 重构堆栈视图结构
**更改 2：** 添加加载指示器

**拆分为 2 个提交：**

```
refactor(ui): 将内容堆栈视图提取为 login view 中的属性

将内联堆栈视图初始化改为基于属性的方法，以更好地组织代码并提高可重用性。将堆栈视图定义从 setupUI 方法移至惰性属性。
```

```
feat(ui): 在 login view 中添加带有活动指示器的加载状态

添加加载指示器覆盖层和 setLoading 方法，以在身份验证期间禁用用户交互并调暗内容。加载时内容透明度降低至 0.5。
```

## 本地化特定指南

### ✅ 良好
```
feat(i18n): 添加英语和土耳其语翻译

创建字符串目录 (Localizable.xcstrings)，包含所有登录屏幕字符串、错误消息和警报的英语和土耳其语翻译。
```

```
build(i18n): 添加土耳其语本地化支持

将土耳其语添加到项目本地化中，并在 Debug 和 Release 配置中启用字符串目录生成 (SWIFT_EMIT_LOC_STRINGS)。
```

```
feat(i18n): 本地化 login view 的 UI 元素

将 LoginView 中的硬编码字符串替换为 NSLocalizedString，包括标题、副标题、标签、占位符和按钮标题。所有面向用户的文本现在都支持本地化。
```

### ❌ 不良
```
feat: 添加全面的多语言支持

为应用添加出色的本地化系统。
```

```
feat: 添加翻译
```

## 破坏性更改

在引入破坏性更改时：

```
feat(api): 更改身份验证响应结构

身份验证端点现在在 'data' 字段中返回用户对象，而不是根级别。这允许在响应中包含额外的元数据。

破坏性更改：更新所有 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): 将 Apple 登录身份验证添加到 AuthService
   将 signInWithApple 方法添加到 AuthService 协议和实现中。使用带有 idToken 和 nonce 的 OAuthProvider 凭证进行 Firebase 身份验证。

4. feat(auth): 将 Apple 登录流程添加到 login view model
   在 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): 将辅助函数转换为静态结构体方法
```
```

```
refactor(ui): 将邮箱验证提取为独立方法

将邮箱验证的正则表达式逻辑从 loginWithEmail 移动到 isValidEmail 方法中，以提高可重用性和可测试性。
```

### 性能

**指定改进内容：**

❌ `perf: 优化登录`

✅
```
perf(auth): 将登录请求时间从 2 秒减少到 500 毫秒

为 Firebase 配置添加请求缓存，以避免重复的网络调用。配置在首次获取后即被缓存。
```

## 正文要求

**正文的最低要求：**

1. **至少 1-2 个完整句子**
2. **具体描述 WHAT（改变了什么）**
3. **解释 WHY（为什么需要此改变，当不明显时）**
4. **提及相关组件/文件（如适用）**
5. **包含从主题中不明显的技术细节**

### 好的正文示例：

```
添加加载指示器覆盖层和 setLoading 方法，在认证期间禁用用户交互并使内容变暗。
```

```
更新 signInWithApple 方法以接受 fullName 参数，并使用 appleCredential 在 Firebase 中正确创建用户配置文件。
```

```
将 LoginView 中的硬编码字符串替换为 NSLocalizedString，用于标题、标签、占位符和按钮。所有 UI 文本现在支持英语和土耳其语翻译。
```

### 差的正文示例：

❌ `添加功能。`（过于模糊）
❌ `更新了文件。`（未解释具体内容）
❌ `修复了 bug。`（未解释具体 bug）
❌ `重构。`（未解释具体重构内容）

## 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): 在登录表单中添加邮箱验证

在发送认证请求之前，使用正则表达式模式实现客户端邮箱验证。验证格式是否符合标准邮箱模式（user@domain.ext），并为无效输入显示错误消息。防止对格式错误的邮箱进行不必要的 Firebase API 调用。
```

**此示例的优点：**
- 明确的类型和范围
- 具体的主题
- 正文解释了验证的作用
- 正文解释了为什么需要它
- 提及了好处（防止 API 调用）
- 未使用禁用词
- 全程使用祈使语气

---

**记住：** 一个好的提交消息应能让某人无需查看 diff 即可理解更改。要具体、简洁、客观，并始终包含有意义的正文。

相关推荐

更多