@aliosmanozturk
# AI 语言模型的 Git 提交指南 ## 核心原则 1. **遵循约定式提交**（https://www.conventionalcommits.org/） 2. **简洁精确** - 不使用华丽辞藻、最高级形容词或不必要的修饰语 3. **关注变更内容，而非实现方式** - 描述变更，而非实现细节 4. **每次提交一个逻辑变更** - 将相关但独立的变更拆分为单独的提交 5. **使用祈使语气** - 用“Add feature”而非“Added feature”或“Adds feature” 6. **始终包含正文** - 绝不使用仅含主题的提交 ## 提交消息结构 ``` <type>(<scope>): <subject> <body> <footer> ``` ### 类型（必填） - `feat`：新功能 - `fix`：缺陷修复 - `refactor`：既不修复缺陷也不添加功能的代码变更 - `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 句话 - **解释变更内容与原因** - 提供上下文 - **每行不超过 72 个字符** - **与主题之间空一行** - **多个变更使用项目符号**（使用 `-` 或 `*`） - **引用问题编号**（如适用） - **在相关时提及具体的类/函数/文件** ### 页脚（可选） - **破坏性变更**：`BREAKING CHANGE: <description>` - **问题引用**：`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 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. ``` **为何好：** - 祈使语气 - 描述了具体问题 - 正文解释了问题和解决方案 --- ### ❌ 坏 ``` refactor(auth): extract helper functions Make code better and more maintainable by extracting functions. ``` **问题：** - 主观（better、maintainable） - 未具体说明哪些函数 ### ✅ 好 ``` 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. ``` **为何好：** - 描述了具体变更 - 提及确切的函数名 - 正文解释了原因和新结构 --- ### ❌ 坏 ``` feat(i18n): add localization ``` **问题：** - 无正文 - 过于含糊 ### ✅ 好 ``` 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. ``` **为何好：** - 提及具体语言 - 范围清晰（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 Add Turkish language to project localizations and enable String Catalog generation (SWIFT_EMIT_LOC_STRINGS) in build settings for Debug and Release configurations. ``` ``` feat(i18n): localize登录视图 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): 添加 Sign in with Apple 权限 添加包含 Sign in with Apple 能力的 entitlements 文件，用于启用 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 方法，以处理 Apple 认证，包括 idToken、nonce 和 fullName。 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 Authentication 的设置过程，包括 Google 登录 和 Apple 登录的配置步骤。 ``` ``` docs: 更新 README 中的安装步骤 添加 SPM 依赖安装说明和 Firebase 设置指南。 ``` ### 重构 ``` refactor(auth): 将辅助函数转换为静态结构体方法 将 Apple 登录辅助函数包装在 AppleSignInHelper 结构体中， 使用静态方法以改善代码组织和命名空间。将 randomNonceString 和 sha256 从私有函数转换为静态方法。 ``` ``` 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. 输出格式： ## Commit [N] **Title:** ``` type(scope): subject ``` **Description:** ``` 解释更改了什么以及为什么的正文文本。提及受影响的 具体组件、类或方法。提供上下文。 ``` **Files to add:** ```bash git add path/to/file ``` ``` ## 最终检查清单 在建议提交之前，请验证： - [ ] 类型正确（feat/fix/refactor/等） - [ ] 范围具体且有意义的 - [ ] 主题使用祈使语气 - [ ] 主题 ≤50 个字符 - [ ] **正文文本存在（必需）** - [ ] **正文至少有 1-2 个完整句子** - [ ] 正文解释了更改了什么（WHAT）以及为什么（WHY） - [ ] 未使用禁用词 - [ ] 没有主观形容词 - [ ] 具体说明更改了什么（WHAT） - [ ] 提及受影响的组件/文件 - [ ] 每个提交一个逻辑更改 - [ ] 文件分组正确 --- ## 示例提交信息（完整） ``` feat(auth): 为登录表单添加邮箱验证 在发送认证请求之前，使用正则表达式模式实现客户端邮箱验证。 验证格式是否匹配标准邮箱模式（user@domain.ext）， 并为无效输入显示错误消息。防止对格式错误的邮箱 发起不必要的 Firebase API 调用。 ``` **为什么这是好的：** - 清晰的类型和范围 - 具体的主题 - 正文解释了验证做什么 - 正文解释了为什么需要它 - 提及了收益（防止 API 调用） - 没有禁用词 - 全程使用祈使语气 --- **记住：** 好的提交信息应能让别人无需查看 diff 就能理解更改。要具体、简洁、客观，并始终包含有意义的正文文本。
