Appearance
Git 提交规范
概述
良好的提交信息是项目可维护性的关键。规范的提交信息不仅有助于代码审查,还能自动生成变更日志,提高团队协作效率。本指南将介绍 Conventional Commits 规范及其在项目中的应用。
提交信息格式
基本格式
<type>(<scope>): <subject>
<body>
<footer>组成部分
1. Type(类型)
用于说明 commit 的类别:
| 类型 | 说明 | 示例 |
|---|---|---|
| feat | 新功能 | feat: 添加用户登录功能 |
| fix | 修复 Bug | fix: 修复登录验证错误 |
| docs | 文档变更 | docs: 更新 README |
| style | 代码格式 | style: 格式化代码 |
| refactor | 重构 | refactor: 重构用户模块 |
| perf | 性能优化 | perf: 优化查询性能 |
| test | 测试 | test: 添加单元测试 |
| build | 构建系统 | build: 更新构建配置 |
| ci | CI 配置 | ci: 添加 GitHub Actions |
| chore | 其他修改 | chore: 更新依赖 |
| revert | 回滚 | revert: 回滚登录功能 |
2. Scope(范围)
可选,用于说明 commit 影响的范围:
feat(auth): 添加 OAuth 登录
fix(api): 修复用户接口错误
docs(readme): 更新安装说明3. Subject(主题)
简短描述,遵循以下规则:
- 使用祈使语气,现在时态
- 首字母小写
- 结尾不加句号
- 不超过 50 个字符
# 好的示例
feat: 添加用户个人资料功能
# 不好的示例
feat: Added user profile feature.
feat: 添加了一个非常详细的用户个人资料功能,包括头像上传、基本信息编辑、密码修改等多个子功能4. Body(正文)
可选,详细描述 commit:
feat: 添加用户个人资料功能
实现用户个人资料管理功能,包括:
- 头像上传和裁剪
- 基本信息编辑
- 密码修改
- 隐私设置
关闭 #1235. Footer(页脚)
可选,用于关闭 Issue 或标记破坏性变更:
Closes #123, #456
BREAKING CHANGE: 用户接口返回格式已变更Conventional Commits
规范说明
Conventional Commits 是一种提交信息规范,它与 SemVer(语义化版本)配合,通过提交信息自动确定版本号变更。
完整示例
新功能
feat: 添加用户认证功能
实现基于 JWT 的用户认证系统:
- 用户注册和登录
- Token 生成和验证
- 密码加密存储
Closes #123Bug 修复
fix(auth): 修复 Token 过期验证错误
修复 JWT Token 过期时间验证逻辑错误,导致用户提前被登出的问题。
问题原因:
- 时间比较使用了错误的单位
- 时区转换不正确
修复方案:
- 统一使用 UTC 时间
- 正确转换时间单位
Fixes #456破坏性变更
feat(api): 重构用户接口返回格式
重构用户相关接口的返回格式,使其更加规范和一致。
BREAKING CHANGE:
- 用户接口返回字段从 `user_name` 改为 `userName`
- 移除了 `user_avatar` 字段,使用 `avatar` 替代
- 时间字段统一使用 ISO 8601 格式
迁移指南:
1. 更新前端代码中的字段名
2. 更新 API 文档
3. 通知所有 API 使用者
Closes #789多个 Issue
feat: 添加用户权限管理
实现基于角色的权限管理系统。
Features:
- 角色管理
- 权限分配
- 权限验证中间件
Closes #101, #102, #103提交模板
Git 模板文件
创建 .git/commit-template 文件:
# <type>(<scope>): <subject>
# |<---- Using a Maximum Of 50 Characters ---->|
# Explain why this change is being made
# |<---- Try To Limit Each Line to a Maximum Of 72 Characters ---->|
# Provide links or keys to any relevant tickets, articles or other resources
# Example: Fixes #123
# --- COMMIT END ---
# Type can be:
# feat (new feature)
# fix (bug fix)
# docs (changes to documentation)
# style (formatting, missing semi colons, etc; no code change)
# refactor (refactoring production code)
# test (adding missing tests, refactoring tests; no production code change)
# chore (updating grunt tasks etc; no production code change)
# perf (performance improvement)
# ci (changes to CI configuration)
# build (changes to build system)
# revert (reverts a previous commit)
# --------------------
# Remember to:
# - Capitalize the subject line
# - Use the imperative mood in the subject line
# - Do not end the subject line with a period
# - Separate subject from body with a blank line
# - Use the body to explain what and why vs. how
# - Can use multiple lines with "-" for bullet points in body
# --------------------配置模板
bash
# 配置提交模板
git config commit.template .git/commit-template
# 或全局配置
git config --global commit.template ~/.git-commit-template使用模板
bash
# 使用模板提交
git commit
# Git 会打开编辑器,显示模板内容
# 填写完成后保存退出自动化工具
Commitlint
安装
bash
# 安装 commitlint
npm install --save-dev @commitlint/cli @commitlint/config-conventional
# 或使用 yarn
yarn add -D @commitlint/cli @commitlint/config-conventional配置
创建 commitlint.config.js:
javascript
module.exports = {
extends: ['@commitlint/config-conventional'],
rules: {
'type-enum': [
2,
'always',
[
'feat',
'fix',
'docs',
'style',
'refactor',
'perf',
'test',
'build',
'ci',
'chore',
'revert',
],
],
'subject-case': [2, 'always', 'lower-case'],
'subject-max-length': [2, 'always', 50],
'body-max-line-length': [2, 'always', 72],
},
};与 Husky 集成
bash
# 安装 Husky
npm install --save-dev husky
# 初始化 Husky
npx husky install
# 添加 commit-msg hook
npx husky add .husky/commit-msg 'npx --no -- commitlint --edit "$1"'Commitizen
安装
bash
# 安装 commitizen 和适配器
npm install --save-dev commitizen cz-conventional-changelog
# 初始化
npx commitizen init cz-conventional-changelog --save-dev --save-exact配置
在 package.json 中添加:
json
{
"scripts": {
"commit": "cz"
},
"config": {
"commitizen": {
"path": "cz-conventional-changelog"
}
}
}使用
bash
# 使用交互式提交
npm run commit
# 或
npx cz自定义适配器
bash
# 安装中文适配器
npm install --save-dev cz-conventional-changelog-zh
# 更新配置
{
"config": {
"commitizen": {
"path": "cz-conventional-changelog-zh"
}
}
}Standard Version
安装
bash
npm install --save-dev standard-version配置
在 package.json 中添加:
json
{
"scripts": {
"release": "standard-version",
"release:first": "standard-version --first-release"
}
}使用
bash
# 首次发布
npm run release:first
# 后续发布
npm run release
# 指定版本类型
npm run release -- --release-as major
npm run release -- --release-as minor
npm run release -- --release-as patch
# 发布预发布版本
npm run release -- --prerelease alphaSemantic Release
安装
bash
npm install --save-dev semantic-release配置
创建 .releaserc 文件:
json
{
"branches": ["main"],
"plugins": [
"@semantic-release/commit-analyzer",
"@semantic-release/release-notes-generator",
"@semantic-release/changelog",
"@semantic-release/npm",
"@semantic-release/git",
"@semantic-release/github"
]
}CI 配置
yaml
# .github/workflows/release.yml
name: Release
on:
push:
branches: [main]
jobs:
release:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Setup Node.js
uses: actions/setup-node@v3
with:
node-version: '18'
- name: Install dependencies
run: npm ci
- name: Release
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
run: npx semantic-release最佳实践
提交粒度
bash
# 好的实践: 小步提交
git add src/auth/login.js
git commit -m "feat(auth): 添加登录功能"
git add src/auth/register.js
git commit -m "feat(auth): 添加注册功能"
git add tests/auth.test.js
git commit -m "test(auth): 添加认证模块测试"
# 不好的实践: 大提交
git add .
git commit -m "feat: 添加用户认证系统,包括登录、注册、密码重置等功能,以及相关测试"原子性提交
bash
# 每个提交应该是一个完整的、可编译的变更
# 好的实践
git commit -m "feat: 添加用户模型"
git commit -m "feat: 添加用户控制器"
git commit -m "feat: 添加用户路由"
# 不好的实践
git commit -m "feat: 添加用户模型(未完成)"
git commit -m "feat: 完成用户模型"提交顺序
bash
# 按照逻辑顺序组织提交
# 1. 先添加依赖
git commit -m "build: 添加 bcrypt 依赖"
# 2. 再添加核心功能
git commit -m "feat: 添加密码加密功能"
# 3. 然后添加测试
git commit -m "test: 添加密码加密测试"
# 4. 最后更新文档
git commit -m "docs: 更新密码加密文档"使用交互式 Rebase
bash
# 整理提交历史
git rebase -i HEAD~5
# 在编辑器中:
pick abc1234 feat: 添加登录功能
squash def5678 fix: 修复登录验证
pick ghi9012 feat: 添加注册功能
squash jkl3456 test: 添加测试
# 合并后:
feat: 添加登录功能
feat: 添加注册功能变更日志生成
自动生成
bash
# 使用 standard-version
npm run release
# 生成的 CHANGELOG.md
# Changelog
All notable changes to this project will be documented in this file.
## [1.0.0] - 2024-01-01
### Features
- 添加用户认证功能
- 添加用户个人资料功能
### Bug Fixes
- 修复登录验证错误
### Breaking Changes
- 用户接口返回格式已变更手动维护
markdown
# Changelog
All notable changes to this project will be documented in this file.
## [Unreleased]
### Added
- 待发布的新功能
### Changed
- 待发布的变更
### Fixed
- 待发布的修复
## [1.0.0] - 2024-01-01
### Added
- 用户认证功能
- 用户个人资料功能
### Changed
- 优化查询性能
### Fixed
- 登录验证错误
### Security
- 修复安全漏洞团队规范
提交规范文档
创建 CONTRIBUTING.md:
markdown
# 贡献指南
## 提交规范
本项目遵循 [Conventional Commits](https://www.conventionalcommits.org/) 规范。
### 提交格式<type>(<scope>): <subject>
### 类型说明
- `feat`: 新功能
- `fix`: Bug 修复
- `docs`: 文档变更
- `style`: 代码格式
- `refactor`: 重构
- `perf`: 性能优化
- `test`: 测试
- `chore`: 其他修改
### 示例feat(auth): 添加 OAuth 登录 fix(api): 修复用户接口错误 docs(readme): 更新安装说明
### 提交前检查
- [ ] 代码通过 lint 检查
- [ ] 测试通过
- [ ] 提交信息符合规范PR 检查清单
markdown
## PR 检查清单
- [ ] 提交信息符合规范
- [ ] 代码遵循项目规范
- [ ] 已添加测试
- [ ] 文档已更新
- [ ] 无破坏性变更(或已说明)总结
良好的提交规范带来的好处:
团队协作:
- 提高代码审查效率
- 便于理解变更意图
- 减少沟通成本
项目管理:
- 自动生成变更日志
- 自动确定版本号
- 便于追踪问题
代码质量:
- 促进原子性提交
- 提高提交质量
- 便于代码回滚
通过使用自动化工具和遵循规范,可以显著提高项目的可维护性和团队协作效率。