175 lines
4.5 KiB
Markdown
175 lines
4.5 KiB
Markdown
## PR 类型建议
|
||
|
||
优先选择最贴近整条分支主结果的一个 type：
|
||
|
||
- 新增 CLI、Agent、MCP 或集成能力：`feat`
|
||
- 修复错误行为：`fix`
|
||
- 只修改文档或 skill：`docs`
|
||
- 主要修改测试：`test`
|
||
- 无外部行为变化的整理：`refactor`
|
||
- 性能优化：`perf`
|
||
- 构建或打包配置：`build`
|
||
- GitHub Actions / CI：`ci`
|
||
- 依赖或内部维护：`chore`
|
||
- 版本发布：`release`
|
||
|
||
## 类型判断补充说明
|
||
|
||
不要因为 diff 里包含逻辑代码就直接判成 `fix`，先看最终结果。
|
||
|
||
优先判断：
|
||
|
||
1. `feat` 只用于对外新增能力，不是“代码变多了”
|
||
2. `fix` 用于修复真实错误行为
|
||
3. 文档、skill、构建和 CI 改动优先使用各自 type
|
||
4. 以用户、CLI 调用方或维护者最终感知到的结果为准
|
||
|
||
示例：
|
||
|
||
- 新增 MCP 查询工具 -> `feat(mcp): ...`
|
||
- 修复版本 fallback 逻辑 -> `fix(version): ...`
|
||
- 更新 agent skill -> `docs(skills): ...`
|
||
- 调整 tsdown 配置 -> `build(config): ...`
|
||
- 修改 PR title workflow -> `ci: ...`
|
||
|
||
## Related Issues 写法
|
||
|
||
有明确 issue 时：
|
||
|
||
- `Closes #123`
|
||
- `Fixes #123`
|
||
- `Refs #123`
|
||
|
||
没有可靠关联时可以不写，或写 `None`。不要编造 issue 编号。
|
||
|
||
## Summary 写法
|
||
|
||
推荐使用 2 至 4 个要点，回答：
|
||
|
||
1. 原先有什么问题，或为什么需要新能力
|
||
2. 这次改变了什么
|
||
3. 是否影响 CLI 参数、输出格式、配置、MCP API 或包内容
|
||
4. 是否有破坏性变化或迁移要求
|
||
|
||
英文示例：
|
||
|
||
```markdown
|
||
## Summary
|
||
|
||
- keep changelog version resolution inside the diff utility
|
||
- simplify the command layer to pass resolved versions
|
||
- preserve existing CLI output with no public API changes
|
||
```
|
||
|
||
中文示例：
|
||
|
||
```markdown
|
||
## Summary
|
||
|
||
- 将 changelog 版本解析收敛到 diff 工具内部
|
||
- 简化命令层，只传递已解析版本
|
||
- 保持现有 CLI 输出，不涉及公开 API 变化
|
||
```
|
||
|
||
## Testing 写法
|
||
|
||
Testing 只记录实际执行并通过的命令，不要根据代码改动猜测结果。
|
||
|
||
常见验证：
|
||
|
||
- 所有 PR：`pnpm lint`
|
||
- 修改 `src/**` 或 `test/**`：`pnpm build`、`pnpm test`
|
||
- CLI、MCP、setup、打包或跨模块集成：考虑 `pnpm test:all`
|
||
- 通用检查：`git diff --check`
|
||
|
||
示例：
|
||
|
||
```markdown
|
||
## Testing
|
||
|
||
- `pnpm lint`
|
||
- `pnpm build`
|
||
- `pnpm test`
|
||
- `git diff --check`
|
||
```
|
||
|
||
未执行时：
|
||
|
||
```markdown
|
||
## Testing
|
||
|
||
- Not run (documentation-only change)
|
||
```
|
||
|
||
若测试失败，要写明失败命令和原因，不能写成通过。
|
||
|
||
## 基线分支判断建议
|
||
|
||
目标是尽量推断“当前分支实际从哪里切出来”，而不是拍脑袋默认 `main`。
|
||
|
||
建议顺序：
|
||
|
||
1. 用户明确指定了 `base branch` -> 直接使用
|
||
2. 查看当前分支是否能从 `reflog` 看出 checkout 来源
|
||
3. 查看 `git branch -vv` 的 tracking / upstream 作为辅助线索
|
||
4. 必要时结合 `merge-base` 比较候选分支
|
||
5. 若仍无法确定，再退回远端默认分支或仓库默认分支
|
||
|
||
建议命令：
|
||
|
||
```bash
|
||
git branch --show-current
|
||
git branch -vv
|
||
git reflog show --date=local $(git branch --show-current)
|
||
git remote show origin
|
||
git merge-base HEAD <candidate-branch>
|
||
```
|
||
|
||
注意：
|
||
|
||
- upstream 不是绝对父分支，只是候选线索
|
||
- `reflog` 最接近真实答案，但不一定一直存在
|
||
- 不确定时要明确告诉用户“这是推断值”
|
||
|
||
## 创建 PR 前确认话术建议
|
||
|
||
在真正执行 `git push` 或 `gh pr create` 前，先给用户确认版草稿：
|
||
|
||
```markdown
|
||
我先整理了一版待提交的 PR 草稿，请你确认：
|
||
|
||
- Target repository: `antdv-next/cli`
|
||
- Base branch: `main`
|
||
- Head branch: `refactor/changelog-version-loading`
|
||
- PR title: `refactor(changelog): move version loading into diff utility`
|
||
- Testing: `pnpm lint`, `pnpm test`
|
||
|
||
如果没问题，我再继续推送并创建 PR；如果你想改 title、base、正文或 Draft 状态，我先更新草稿。
|
||
```
|
||
|
||
## PR 标题示例
|
||
|
||
`antdv-next/cli` 的 PR 标题使用英文，并遵循：
|
||
|
||
- `<type>: <subject>`
|
||
- `<type>(<scope>): <subject>`
|
||
|
||
subject 必须以小写字符开头，以通过 `.github/workflows/validate-pr-title.yml`。
|
||
|
||
推荐示例：
|
||
|
||
- `feat(mcp): add component changelog query tool`
|
||
- `fix(version): resolve missing patch versions with fallback`
|
||
- `docs(skills): clarify CLI usage for agents`
|
||
- `refactor(changelog): move metadata loading into diff utility`
|
||
- `build(config): optimize tsdown bundle output`
|
||
- `ci: validate pull request title format`
|
||
- `chore(package): include skills in published files`
|
||
|
||
不要这样写：
|
||
|
||
- `修复版本解析问题`
|
||
- `Update version resolver`
|
||
- `fix issues`
|
||
- `some improvements`
|