branch-pr

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

When to Use

使用场景

Use this skill when:

Creating a pull request for any change
Preparing a branch for submission
Helping a contributor open a PR

当以下情况时使用本技能：

为任何变更创建拉取请求（PR）
准备用于提交的分支
协助贡献者发起PR

Critical Rules

核心规则

Every PR MUST link an approved issue — no exceptions
Every PR MUST have exactly one
type:*
label
Automated checks must pass before merge is possible
Blank PRs without issue linkage will be blocked by GitHub Actions

每个PR必须关联一个已获批的议题——无例外
每个PR必须恰好包含一个
type:*
标签
自动化检查必须通过才能合并
未关联议题的空白PR将被GitHub Actions拦截

Workflow

工作流

1. Verify issue has `status:approved` label
2. Create branch: type/description (see Branch Naming below)
3. Implement changes with conventional commits
4. Run shellcheck on modified scripts
5. Open PR using the template
6. Add exactly one type:* label
7. Wait for automated checks to pass

1. 验证议题是否带有`status:approved`标签
2. 创建分支：type/description（见下方分支命名规则）
3. 使用规范提交（Conventional Commits）实现变更
4. 对修改的脚本运行shellcheck检查
5. 使用模板发起PR
6. 添加恰好一个type:*标签
7. 等待自动化检查通过

Branch Naming

分支命名

Branch names MUST match this regex:

^(feat|fix|chore|docs|style|refactor|perf|test|build|ci|revert)\/[a-z0-9._-]+$

Format:

type/description

— lowercase, no spaces, only

a-z0-9._-

in description.

Type	Branch pattern	Example
Feature	`feat/<description>`	`feat/user-login`
Bug fix	`fix/<description>`	`fix/zsh-glob-error`
Chore	`chore/<description>`	`chore/update-ci-actions`
Docs	`docs/<description>`	`docs/installation-guide`
Style	`style/<description>`	`style/format-scripts`
Refactor	`refactor/<description>`	`refactor/extract-shared-logic`
Performance	`perf/<description>`	`perf/reduce-startup-time`
Test	`test/<description>`	`test/add-setup-coverage`
Build	`build/<description>`	`build/update-shellcheck`
CI	`ci/<description>`	`ci/add-branch-validation`
Revert	`revert/<description>`	`revert/broken-setup-change`

分支名称必须匹配以下正则表达式：

^(feat|fix|chore|docs|style|refactor|perf|test|build|ci|revert)\/[a-z0-9._-]+$

格式：

type/description

——全小写，无空格，描述部分仅允许使用

a-z0-9._-

。

类型	分支格式	示例
功能新增	`feat/<description>`	`feat/user-login`
Bug修复	`fix/<description>`	`fix/zsh-glob-error`
日常维护	`chore/<description>`	`chore/update-ci-actions`
文档更新	`docs/<description>`	`docs/installation-guide`
格式调整	`style/<description>`	`style/format-scripts`
代码重构	`refactor/<description>`	`refactor/extract-shared-logic`
性能优化	`perf/<description>`	`perf/reduce-startup-time`
测试相关	`test/<description>`	`test/add-setup-coverage`
构建相关	`build/<description>`	`build/update-shellcheck`
CI配置	`ci/<description>`	`ci/add-branch-validation`
版本回滚	`revert/<description>`	`revert/broken-setup-change`

PR Body Format

PR正文格式

The PR template is at

.github/PULL_REQUEST_TEMPLATE.md

. Every PR body MUST contain:

PR模板位于

.github/PULL_REQUEST_TEMPLATE.md

。每个PR正文必须包含以下内容：

1. Linked Issue (REQUIRED)

1. 关联议题（必填）

markdown

Closes #<issue-number>

Valid keywords:

Closes #N

Fixes #N

Resolves #N

(case insensitive). The linked issue MUST have the

status:approved

label.

markdown

Closes #<issue-number>

有效关键词：

Closes #N

、

Fixes #N

、

Resolves #N

（不区分大小写）。关联的议题必须带有

status:approved

标签。

2. PR Type (REQUIRED)

2. PR类型（必填）

Check exactly ONE in the template and add the matching label:

Checkbox	Label to add
Bug fix	`type:bug`
New feature	`type:feature`
Documentation only	`type:docs`
Code refactoring	`type:refactor`
Maintenance/tooling	`type:chore`
Breaking change	`type:breaking-change`

在模板中勾选恰好一项，并添加对应的标签：

复选框	需添加的标签
Bug修复	`type:bug`
新功能	`type:feature`
仅文档更新	`type:docs`
代码重构	`type:refactor`
维护/工具类	`type:chore`
破坏性变更	`type:breaking-change`

3. Summary

3. 变更摘要

1-3 bullet points of what the PR does.

用1-3个要点说明PR的内容。

4. Changes Table

4. 变更表格

markdown

| File | Change |
|------|--------|
| `path/to/file` | What changed |

markdown

| 文件 | 变更内容 |
|------|--------|
| `path/to/file` | 具体变更 |

5. Test Plan

5. 测试计划

markdown

- [x] Scripts run without errors: `shellcheck scripts/*.sh`
- [x] Manually tested the affected functionality
- [x] Skills load correctly in target agent

markdown

- [x] 脚本运行无错误：`shellcheck scripts/*.sh`
- [x] 手动测试了受影响的功能
- [x] 技能在目标Agent中加载正常

6. Contributor Checklist

6. 贡献者检查清单

All boxes must be checked:

Linked an approved issue
Added exactly one
```
type:*
```
label
Ran shellcheck on modified scripts
Skills tested in at least one agent
Docs updated if behavior changed
Conventional commit format
No
```
Co-Authored-By
```
trailers

所有选项必须勾选：

关联了已获批的议题
添加了恰好一个
```
type:*
```
标签
对修改的脚本运行了shellcheck检查
技能已在至少一个Agent中测试
若行为变更则已更新文档
遵循规范提交（Conventional Commits）格式
无
```
Co-Authored-By
```
标记

Automated Checks (all must pass)

自动化检查（全部必须通过）

Check	Job name	What it verifies
PR Validation	`Check Issue Reference`	Body contains `Closes/Fixes/Resolves #N`
PR Validation	`Check Issue Has status:approved`	Linked issue has `status:approved`
PR Validation	`Check PR Has type:* Label`	PR has exactly one `type:*` label
CI	`Shellcheck`	Shell scripts pass `shellcheck`

检查项	任务名称	验证内容
PR验证	`Check Issue Reference`	正文包含 `Closes/Fixes/Resolves #N`
PR验证	`Check Issue Has status:approved`	关联的议题带有 `status:approved` 标签
PR验证	`Check PR Has type:* Label`	PR恰好包含一个 `type:*` 标签
CI	`Shellcheck`	Shell脚本通过 `shellcheck` 检查

Conventional Commits

规范提交（Conventional Commits）

Commit messages MUST match this regex:

^(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)(\([a-z0-9\._-]+\))?!?: .+

Format:

type(scope): description

type: description

type

— required, one of:

build

chore

ci

docs

feat

fix

perf

refactor

revert

style

test

```
(scope)
```
— optional, lowercase with
```
a-z0-9._-
```
```
!
```
— optional, indicates breaking change
```
description
```
— required, starts after
```
: 
```

Type-to-label mapping:

Commit type	PR label
`feat`	`type:feature`
`fix`	`type:bug`
`docs`	`type:docs`
`refactor`	`type:refactor`
`chore`	`type:chore`
`style`	`type:chore`
`perf`	`type:feature`
`test`	`type:chore`
`build`	`type:chore`
`ci`	`type:chore`
`revert`	`type:bug`
`feat!` / `fix!`	`type:breaking-change`

Examples:

feat(scripts): add Codex support to setup.sh
fix(skills): correct topic key format in sdd-apply
docs(readme): update multi-model configuration guide
refactor(skills): extract shared persistence logic
chore(ci): add shellcheck to PR validation workflow
perf(scripts): reduce setup.sh execution time
style(skills): fix markdown formatting
test(scripts): add setup.sh integration tests
ci(workflows): add branch name validation
revert: undo broken setup change
feat!: redesign skill loading system

提交信息必须匹配以下正则表达式：

^(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)(\([a-z0-9\._-]+\))?!?: .+

格式：

type(scope): description

或

type: description

```
type
```
——必填，可选值：
```
build
```
、
```
chore
```
、
```
ci
```
、
```
docs
```
、
```
feat
```
、
```
fix
```
、
```
perf
```
、
```
refactor
```
、
```
revert
```
、
```
style
```
、
```
test
```
```
(scope)
```
——可选，全小写，允许使用
```
a-z0-9._-
```
```
!
```
——可选，表示破坏性变更
```
description
```
——必填，位于
```
: 
```
之后

提交类型与PR标签的映射：

提交类型	PR标签
`feat`	`type:feature`
`fix`	`type:bug`
`docs`	`type:docs`
`refactor`	`type:refactor`
`chore`	`type:chore`
`style`	`type:chore`
`perf`	`type:feature`
`test`	`type:chore`
`build`	`type:chore`
`ci`	`type:chore`
`revert`	`type:bug`
`feat!` / `fix!`	`type:breaking-change`

示例：

feat(scripts): add Codex support to setup.sh
fix(skills): correct topic key format in sdd-apply
docs(readme): update multi-model configuration guide
refactor(skills): extract shared persistence logic
chore(ci): add shellcheck to PR validation workflow
perf(scripts): reduce setup.sh execution time
style(skills): fix markdown formatting
test(scripts): add setup.sh integration tests
ci(workflows): add branch name validation
revert: undo broken setup change
feat!: redesign skill loading system

Commands

命令

bash

undefined

bash

undefined

Create branch

创建分支

git checkout -b feat/my-feature main

Run shellcheck before pushing

推送前运行shellcheck

shellcheck scripts/*.sh

Push and create PR

推送并创建PR

git push -u origin feat/my-feature gh pr create --title "feat(scope): description" --body "Closes #N"

Add type label to PR

为PR添加类型标签

gh pr edit <pr-number> --add-label "type:feature"

undefined

gh pr edit <pr-number> --add-label "type:feature"

undefined