9.0 KiB

Raw Blame History

name

version

description

metadata

gitlink-commit-quality

1.0.0

提交质量守护：检查提交信息规范（Conventional Commits）、PR 描述完整性、分支命名规范、变更文件合理性审核。当用户需要规范团队提交流程、审查代码提交质量时触发。

requires

cliHelp

bins

gitlink-cli

gitlink-cli pr --help

gitlink-commit-quality（提交质量守护）

CRITICAL — 开始前必须先阅读 ../gitlink-shared/SKILL.md。 CRITICAL — GitLink 操作只能用 gitlink-cli。

前置条件： 先阅读 ../gitlink-shared/SKILL.md 了解认证和全局参数。

功能概述

本技能覆盖开发流程中的提交质量管控，包括：

Commit Message 规范检查 — 验证是否符合 Conventional Commits 规范
PR 质量检查 — PR 标题、描述、关联 Issue 完整性
分支命名规范 — 检查分支名是否符合团队约定
变更合理性检查 — 一次提交是否改动过多、是否有无关文件混入

一、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 的所有提交信息

# 获取 PR 关联的提交列表
gitlink-cli pr +diff --id <pr_id> --owner <owner> --repo <repo> --format json

# 或通过 Raw API 获取提交详情
gitlink-cli pr +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 信息

# 获取 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 描述：

## 变更说明

<!-- 简述本次 PR 做了什么 -->

## 原因/背景

<!-- 为什么需要这个改动？关联的 Issue？ -->
Closes #<issue_number>

## 测试方案

<!-- 如何验证这次改动是正确的？ -->
- [ ] 单元测试通过
- [ ] 手动测试步骤：...

## 截图（如有 UI 变更）

<!-- 添加 before/after 截图 -->

## Checklist

- [ ] 代码符合项目编码规范
- [ ] 相关文档已更新
- [ ] 测试覆盖新增/修改的代码

三、分支命名规范检查

获取分支信息

# 从 PR 信息中获取分支名
gitlink-cli pr +view --id <pr_id> --format json
# 关注 head_branch 字段

# 列出所有分支
gitlink-cli branch +list --owner <owner> --repo <repo> --format json

不合规的分支名示例

不合规	问题	建议
`test123`	无意义	`test/add-login-unit-tests`
`dev` / `development`	过于宽泛	使用具体功能描述
`zhangsan_feature`	用人名命名	用功能命名
`fix-bug`	不够具体	`fix/login-crash-on-empty-password`
含中文	可能导致编码问题	使用英文

四、变更合理性检查

获取变更文件

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*（文件名）

五、完整质量报告输出格式

## 📋 提交质量检查报告

**检查范围：** 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 合并前的质量门禁：

# 在 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 新增的提交
✅ 团队约定优先：如团队有自己的规范，以团队规范为准，本技能提供通用参考

9.0 KiB Raw Blame History Unescape Escape