forked from Gitlink/gitlink-cli
321 lines
9.1 KiB
Markdown
321 lines
9.1 KiB
Markdown
---
|
||
name: gitlink-commit-quality
|
||
version: 1.0.0
|
||
description: "提交质量守护：检查提交信息规范（Conventional Commits）、PR 描述完整性、分支命名规范、变更文件合理性审核。当用户需要规范团队提交流程、审查代码提交质量时触发。"
|
||
metadata:
|
||
requires:
|
||
bins: ["gitlink-cli"]
|
||
cliHelp: "gitlink-cli pr --help"
|
||
---
|
||
|
||
# gitlink-commit-quality（提交质量守护）
|
||
|
||
**CRITICAL — 开始前必须先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)。**
|
||
**CRITICAL — GitLink 操作只能用 `gitlink-cli`。**
|
||
|
||
> **前置条件：** 先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md) 了解认证和全局参数。
|
||
|
||
## 功能概述
|
||
|
||
本技能覆盖开发流程中的提交质量管控，包括：
|
||
|
||
1. **Commit Message 规范检查** — 验证是否符合 Conventional Commits 规范
|
||
2. **PR 质量检查** — PR 标题、描述、关联 Issue 完整性
|
||
3. **分支命名规范** — 检查分支名是否符合团队约定
|
||
4. **变更合理性检查** — 一次提交是否改动过多、是否有无关文件混入
|
||
|
||
---
|
||
|
||
## 一、Commit Message 规范检查
|
||
|
||
### Conventional Commits 规范
|
||
|
||
标准格式：
|
||
```
|
||
<type>(<scope>): <description>
|
||
|
||
[optional body]
|
||
|
||
[optional footer(s)]
|
||
```
|
||
|
||
**合法的 type 值：**
|
||
|
||
| type | 含义 | 示例 |
|
||
|------|------|------|
|
||
| `feat` | 新增功能 | `feat(auth): 添加 JWT 认证` |
|
||
| `fix` | 修复 Bug | `fix(login): 修复密码验证逻辑错误` |
|
||
| `docs` | 文档变更 | `docs: 更新 API 接口文档` |
|
||
| `style` | 代码格式（不影响逻辑） | `style: 统一缩进为 4 空格` |
|
||
| `refactor` | 代码重构 | `refactor(user): 提取公共验证逻辑` |
|
||
| `perf` | 性能优化 | `perf(query): 优化数据库查询索引` |
|
||
| `test` | 测试相关 | `test(auth): 补充登录测试用例` |
|
||
| `build` | 构建系统变更 | `build: 升级 Go 版本到 1.21` |
|
||
| `ci` | CI 配置变更 | `ci: 添加 lint 检查步骤` |
|
||
| `chore` | 其他杂项 | `chore: 更新 .gitignore` |
|
||
| `revert` | 回滚提交 | `revert: revert feat(auth): ...` |
|
||
|
||
### 检查 PR 的所有提交信息
|
||
|
||
```bash
|
||
# 获取 PR 关联的提交列表
|
||
gitlink-cli pr +diff --id <pr_id> --owner <owner> --repo <repo> --format json
|
||
|
||
# 或通过 Raw API 获取提交详情
|
||
gitlink-cli api GET /:owner/:repo/pulls/:pr_id/commits --format json
|
||
```
|
||
|
||
### Commit Message 质量检查清单
|
||
|
||
对每条提交信息执行以下检查：
|
||
|
||
```
|
||
✅ 必须检查：
|
||
□ type 是否是合法值（feat/fix/docs/style/refactor/perf/test/build/ci/chore/revert）
|
||
□ description 是否是中文或英文（不能是无意义内容如 "update"、"fix"、"tmp"、"xxx"）
|
||
□ description 首字母是否小写（英文时）
|
||
□ description 末尾是否没有句号
|
||
□ 整条信息是否超过 72 个字符（首行）
|
||
|
||
⚠️ 建议检查：
|
||
□ scope 是否有意义（如 auth/user/api/db 等模块名）
|
||
□ Breaking Change 是否在 footer 中标注（BREAKING CHANGE: ...）
|
||
□ 关联 Issue 是否在 footer 中标注（Closes #123 / Fixes #456）
|
||
```
|
||
|
||
### 不合规示例 vs 合规示例
|
||
|
||
| 不合规 | 问题 | 合规写法 |
|
||
|--------|------|---------|
|
||
| `update` | 无意义描述 | `feat(user): 新增用户头像上传功能` |
|
||
| `fix bug` | 无具体说明 | `fix(login): 修复手机号登录时验证码未清除的问题` |
|
||
| `WIP` | 临时提交混入 | 应在本地整理后再提交 |
|
||
| `Feat: Add search` | type 大写 | `feat(search): 添加全文搜索功能` |
|
||
| `feat: 添加搜索.` | 末尾有句号 | `feat(search): 添加搜索功能` |
|
||
|
||
---
|
||
|
||
## 二、PR 质量检查
|
||
|
||
### 获取 PR 信息
|
||
|
||
```bash
|
||
# 获取 PR 详情
|
||
gitlink-cli pr +view --id <pr_id> --owner <owner> --repo <repo> --format json
|
||
```
|
||
|
||
### PR 质量检查清单
|
||
|
||
```
|
||
✅ 必须检查：
|
||
□ PR 标题是否符合 Conventional Commits 格式
|
||
□ PR 描述是否有实质内容（不能为空或仅有一行）
|
||
□ PR 描述是否说明了"做了什么"和"为什么这么做"
|
||
□ PR 变更文件数量是否合理（建议单次 PR < 20 文件）
|
||
□ PR 变更行数是否合理（建议单次 PR < 500 行净变更）
|
||
|
||
⚠️ 建议检查：
|
||
□ PR 描述是否关联了对应 Issue（格式：Closes #123）
|
||
□ 是否有 Test Plan（如何验证这次改动）
|
||
□ 是否有截图（UI 改动）
|
||
□ 是否更新了相关文档
|
||
```
|
||
|
||
### PR 描述模板（推荐）
|
||
|
||
在 Review 评论中可以建议作者按以下模板完善 PR 描述：
|
||
|
||
```markdown
|
||
## 变更说明
|
||
|
||
<!-- 简述本次 PR 做了什么 -->
|
||
|
||
## 原因/背景
|
||
|
||
<!-- 为什么需要这个改动？关联的 Issue？ -->
|
||
Closes #<issue_number>
|
||
|
||
## 测试方案
|
||
|
||
<!-- 如何验证这次改动是正确的？ -->
|
||
- [ ] 单元测试通过
|
||
- [ ] 手动测试步骤：...
|
||
|
||
## 截图（如有 UI 变更）
|
||
|
||
<!-- 添加 before/after 截图 -->
|
||
|
||
## Checklist
|
||
|
||
- [ ] 代码符合项目编码规范
|
||
- [ ] 相关文档已更新
|
||
- [ ] 测试覆盖新增/修改的代码
|
||
```
|
||
|
||
---
|
||
|
||
## 三、分支命名规范检查
|
||
|
||
### 获取分支信息
|
||
|
||
```bash
|
||
# 从 PR 信息中获取分支名
|
||
gitlink-cli pr +view --id <pr_id> --format json
|
||
# 关注 head_branch 字段
|
||
|
||
# 列出所有分支
|
||
gitlink-cli branch +list --owner <owner> --repo <repo> --format json
|
||
```
|
||
|
||
### 推荐的分支命名规范
|
||
|
||
```
|
||
格式：<type>/<short-description>
|
||
或： <type>/<issue-id>-<short-description>
|
||
|
||
示例：
|
||
feat/user-authentication
|
||
fix/login-password-validation
|
||
fix/123-token-expiry-bug
|
||
docs/api-reference-update
|
||
refactor/extract-auth-middleware
|
||
release/v1.2.0
|
||
hotfix/critical-security-patch
|
||
```
|
||
|
||
### 不合规的分支名示例
|
||
|
||
| 不合规 | 问题 | 建议 |
|
||
|--------|------|------|
|
||
| `test123` | 无意义 | `test/add-login-unit-tests` |
|
||
| `dev` / `development` | 过于宽泛 | 使用具体功能描述 |
|
||
| `zhangsan_feature` | 用人名命名 | 用功能命名 |
|
||
| `fix-bug` | 不够具体 | `fix/login-crash-on-empty-password` |
|
||
| 含中文 | 可能导致编码问题 | 使用英文 |
|
||
|
||
---
|
||
|
||
## 四、变更合理性检查
|
||
|
||
### 获取变更文件
|
||
|
||
```bash
|
||
gitlink-cli pr +files --id <pr_id> --owner <owner> --repo <repo> --format json
|
||
```
|
||
|
||
### 变更文件审核要点
|
||
|
||
```
|
||
📊 规模检查：
|
||
□ 变更文件数 > 20：建议拆分成多个 PR
|
||
□ 净变更行数 > 500：建议拆分
|
||
□ 单个文件变更 > 300 行：值得重点关注
|
||
|
||
🔍 文件类型检查：
|
||
□ 是否有无关文件混入（如调试文件、个人 IDE 配置）
|
||
□ 是否有 .env 文件、密钥文件被提交
|
||
□ 是否有二进制文件或大文件（图片、视频等）
|
||
□ 是否有自动生成文件（lock 文件、build 产物）混入功能 PR
|
||
|
||
⚠️ 敏感文件检查（高优先级）：
|
||
□ .env / .env.local / .env.production
|
||
□ *.pem / *.key / *.p12 / *.pfx
|
||
□ id_rsa / id_dsa
|
||
□ config/secret* / credentials*
|
||
□ *password* / *secret* / *token*（文件名）
|
||
```
|
||
|
||
---
|
||
|
||
## 五、完整质量报告输出格式
|
||
|
||
```markdown
|
||
## 📋 提交质量检查报告
|
||
|
||
**检查范围：** PR #42 — feat: 添加用户认证模块
|
||
|
||
---
|
||
|
||
### 1. PR 基本信息
|
||
|
||
| 项目 | 检查结果 |
|
||
|------|---------|
|
||
| PR 标题格式 | ✅ 符合规范 |
|
||
| PR 描述完整性 | ⚠️ 缺少 Test Plan |
|
||
| 关联 Issue | ✅ Closes #88 |
|
||
| 变更规模 | ✅ 12 文件 / +248 -89 行 |
|
||
|
||
---
|
||
|
||
### 2. 提交信息检查
|
||
|
||
| 提交 SHA | 提交信息 | 检查结果 |
|
||
|---------|---------|---------|
|
||
| `a1b2c3d` | feat(auth): 添加 JWT 生成 | ✅ 合规 |
|
||
| `e4f5g6h` | fix login bug | ❌ 不合规 |
|
||
| `i7j8k9l` | WIP | ❌ 不合规 |
|
||
|
||
**问题详情：**
|
||
|
||
**[1] 提交 e4f5g6h: "fix login bug"**
|
||
- 问题：缺少规范 type 格式，描述过于模糊
|
||
- 建议：`fix(login): 修复登录时密码验证逻辑错误`
|
||
|
||
**[2] 提交 i7j8k9l: "WIP"**
|
||
- 问题：临时 WIP 提交不应出现在正式 PR 中
|
||
- 建议：`git rebase -i HEAD~2` 将相关提交合并，并写一个规范的提交信息
|
||
|
||
---
|
||
|
||
### 3. 分支命名
|
||
|
||
| 分支名 | 检查结果 |
|
||
|-------|---------|
|
||
| `feature/user-auth` | ✅ 符合规范 |
|
||
|
||
---
|
||
|
||
### 4. 变更文件审核
|
||
|
||
✅ 规模合理（12 文件，248 行净增加）
|
||
|
||
⚠️ **发现 1 个潜在问题：**
|
||
- `config/app.env`：`.env` 文件被提交，请确认是否包含敏感配置
|
||
|
||
---
|
||
|
||
### 5. 改进建议
|
||
|
||
1. 完善 PR 描述，添加 Test Plan（必须）
|
||
2. 修复 2 条不规范的提交信息（建议通过 rebase 整理）
|
||
3. 确认 `.env` 文件是否应该提交，建议加入 `.gitignore`
|
||
|
||
---
|
||
|
||
**总体评级：** ⚠️ 需要改进（2个必须修复，1个建议）
|
||
```
|
||
|
||
---
|
||
|
||
## 六、配合 CI 的自动化质量门禁
|
||
|
||
可将以下检查逻辑集成到 CI 流程，作为 PR 合并前的质量门禁：
|
||
|
||
```bash
|
||
# 在 CI 中检查最新提交的 commit message
|
||
git log --oneline -10
|
||
|
||
# 统计 PR 变更规模
|
||
gitlink-cli pr +files --id $PR_ID --format json | \
|
||
jq '{files: [.data[].filename] | length, additions: [.data[].additions] | add, deletions: [.data[].deletions] | add}'
|
||
```
|
||
|
||
---
|
||
|
||
## 注意事项
|
||
|
||
- ✅ **提交规范的推行应循序渐进**，先建议后强制
|
||
- ✅ **WIP 提交**：允许在开发分支中存在，但合并到主干前需 squash/rebase
|
||
- ⚠️ **历史遗留**：老代码的提交不在检查范围，只检查本次 PR 新增的提交
|
||
- ✅ **团队约定优先**：如团队有自己的规范，以团队规范为准，本技能提供通用参考
|