1. 前言 (Introduction)
制定本规范的目的是为了保持代码仓库的整洁，提高团队协作效率，便于代码审查（Code Review）以及实现自动化的版本管理和变更日志（Changelog）生成。
核心原则：
- 清晰（Clear）： 命名应当能一眼看出用途。
- 一致（Consistent）： 团队所有成员需遵循同一套规则。
- 可追踪（Traceable）： 能够方便地回溯历史和定位问题。
2. 分支命名规范 (Branch Naming)
分支命名统一使用 小写字母，单词之间用 连字符（-） 分隔。
2.1 基础结构
text
<type>/<issue-id>/<description>
注：issue-id 为可选，若关联了 Jira/GitLab Issue ID，建议加上。
2.2 常用分支类型 (<type>)
| 分支类型 | 命名示例 | 说明 |
|---|---|---|
| master / main | - | 主分支，受保护，存放随时可部署的生产环境代码。 |
| develop | - | 开发主分支，存放最新的开发进度，合并所有 Feature 分支。 |
| feature | feature/login-pagefeature/PROJ-123/add-auth | 新功能分支。从 develop 检出，开发完成后合并回 develop。 |
| bugfix | bugfix/fix-header-alignbugfix/PROJ-456/nav-error | 非紧急修复分支。通常在测试阶段发现的问题，从 develop 检出。 |
| hotfix | hotfix/v1.0.1-security-patch | 紧急修复分支。线上生产环境 Bug，从 master 检出，修复后合并回 master 和 develop。 |
| release | release/v1.2.0 | 发布分支。预发布阶段，从 develop 检出，只修 Bug 不加新功能，最终合并至 master。 |
| refactor | refactor/user-service | 重构分支。不改变逻辑，仅优化代码结构。 |
2.3 命名规则
- ❌
Feature/Login(不要大写) - ❌
feature_login(不要用下划线) - ❌
feature/add login button(不要有空格) - ✅
feature/add-login-button
3. Commit 信息规范 (Commit Message)
我们遵循业界通用的 Conventional Commits 规范。
3.1 提交格式
text
<type>(<scope>): <subject>
// 空一行
<body>
// 空一行
<footer>
- Header (必填): 包含 Type, Scope (可选) 和 Subject。
- Body (选填): 详细描述，解释 "为什么" 修改，而不是 "怎么" 修改。
- Footer (选填): 关联 Issue 或备注 Breaking Changes。
3.2 Header 类型 (<type>)
| 类型 | 说明 | Emoji (可选) |
|---|---|---|
| feat | 新增功能 (Feature) | ✨ :sparkles: |
| fix | 修复 Bug | 🐛 :bug: |
| docs | 仅修改文档 (Documentation) | 📝 :memo: |
| style | 格式修改，不影响代码运行 (空格, 分号等) | 💄 :lipstick: |
| refactor | 代码重构 (既不是新增功能也不是修 Bug) | ♻️ :recycle: |
| perf | 性能优化 (Performance) | ⚡️ :zap: |
| test | 增加或修改测试代码 | ✅ :white_check_mark: |
| chore | 构建过程或辅助工具的变动 (构建流, 依赖管理) | 🔧 :wrench: |
| revert | 回退版本 | ⏪ :rewind: |
| ci | CI/CD 配置文件或脚本修改 | 👷 :construction_worker: |
3.3 示例
示例 1：新增功能
text
feat(user): 添加用户登录接口
实现了基于 JWT 的用户登录验证功能。
包含：
1. Controller 接口定义
2. Service 逻辑实现
3. 单元测试
Closes #123
示例 2：修复 Bug
text
fix(ui): 修复导航栏在移动端错位的问题
调整了 flex 布局参数，确保在 iPhone SE 尺寸下显示正常。
示例 3：Breaking Change
text
refactor(auth)!: 移除旧版 token 验证逻辑
BREAKING CHANGE: `verifyToken` 方法参数由 string 变更为 object，所有调用方需更新。
4. 标签命名规范 (Tagging)
Tag 用于标记发布的版本，必须遵循 Semantic Versioning 2.0.0 (语义化版本)。
4.1 格式
v<Major>.<Minor>.<Patch>[-<Pre-release>]
4.2 字段说明
- Major (主版本号): 当你做了不兼容的 API 修改 (Breaking Changes)。
- Minor (次版本号): 当你做了向下兼容的功能性新增 (New Features)。
- Patch (修订号): 当你做了向下兼容的问题修正 (Bug Fixes)。
4.3 示例
v1.0.0: 初始正式版本v1.0.1: 修复了一些 Bugv1.1.0: 新增了一些功能v2.0.0: 架构升级，接口不兼容v1.1.0-alpha.1: 内测版v1.1.0-beta: 公测版v1.1.0-rc: 候选发布版 (Release Candidate)
5. 工作流最佳实践 (Best Practices)
- 原子提交 (Atomic Commits)
- 一个 Commit 只做一件事。不要将格式化代码和修复 Bug 混在一个 Commit 里。
- 不要提交垃圾文件
- 确保
.gitignore配置正确，不要提交.idea,.vscode,node_modules,dist等文件。
- 确保
- 勤合并，早解决冲突
- Feature 分支开发过程中，建议定期 merge/rebase
develop分支的代码，避免最后合并时冲突过多。
- Feature 分支开发过程中，建议定期 merge/rebase
- 禁止强推 (No Force Push)
- 严禁在公共分支（master, develop, release）上使用
git push -f。
- 严禁在公共分支（master, develop, release）上使用
- Pull Request (PR) / Merge Request (MR)
- 代码合并进主分支前，必须通过 PR/MR 机制，并至少经过一人 Code Review。
