diff --git a/skills/gitlink-commit-quality/SKILL.md b/skills/gitlink-commit-quality/SKILL.md new file mode 100644 index 0000000..939261f --- /dev/null +++ b/skills/gitlink-commit-quality/SKILL.md @@ -0,0 +1,320 @@ +--- +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 规范 + +标准格式： +``` +(): + +[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 --owner --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 --owner --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 +## 变更说明 + + + +## 原因/背景 + + +Closes # + +## 测试方案 + + +- [ ] 单元测试通过 +- [ ] 手动测试步骤：... + +## 截图（如有 UI 变更） + + + +## Checklist + +- [ ] 代码符合项目编码规范 +- [ ] 相关文档已更新 +- [ ] 测试覆盖新增/修改的代码 +``` + +--- + +## 三、分支命名规范检查 + +### 获取分支信息 + +```bash +# 从 PR 信息中获取分支名 +gitlink-cli pr +view --id --format json +# 关注 head_branch 字段 + +# 列出所有分支 +gitlink-cli branch +list --owner --repo --format json +``` + +### 推荐的分支命名规范 + +``` +格式：/ +或： /- + +示例： + 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 --owner --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 新增的提交 +- ✅ **团队约定优先**：如团队有自己的规范，以团队规范为准，本技能提供通用参考