create-pr

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Create Pull Request

创建Pull Request

Create a PR with proper conventions: local verification, Conventional Commits title, a templated body, and an optional linked ticket. This skill is language- and framework-agnostic — substitute your project's actual build, lint, test, and format commands where examples are shown.

创建符合规范的PR：包含本地验证、Conventional Commits格式标题、模板化正文，以及可选的关联工单。此技能与语言和框架无关——示例中展示的命令可替换为项目实际的构建、代码检查、测试和格式化命令。

Prerequisites

前置条件

Before starting, verify:

Current branch has commits not on the base branch (
```
git log origin/<base-branch>..HEAD --oneline
```
)
Branch is pushed to remote (
```
git push -u origin HEAD
```
if not)
No uncommitted changes that should be included (
```
git status
```
)

开始前，请确认：

当前分支存在未合并到基准分支的提交（执行
```
git log origin/<base-branch>..HEAD --oneline
```
）
分支已推送到远程仓库（若未推送，执行
```
git push -u origin HEAD
```
）
没有应纳入提交的未更改内容（执行
```
git status
```
检查）

Workflow

工作流程

1. Understand the Changes

1. 理解变更内容

Run in parallel:

bash

git log origin/<base-branch>..HEAD --oneline
git diff origin/<base-branch>..HEAD --stat

Determine:

What changed: Which modules, packages, services, or directories were modified

Change type:

feat

fix

docs

refactor

test

chore

perf

ci

build

revert

Scope: Primary module/package/service affected (use directory name or
```
monorepo
```
/
```
repo
```
for cross-cutting changes)
Is this a code change?: If the PR modifies source code (not only docs, markdown, or config-only changes), run the local verification checklist in step 2 before creating the PR.

并行执行以下命令：

bash

git log origin/<base-branch>..HEAD --oneline
git diff origin/<base-branch>..HEAD --stat

确定：

变更内容：哪些模块、包、服务或目录被修改

变更类型：

feat

、

fix

、

docs

、

refactor

、

test

、

chore

、

perf

、

ci

、

build

、

revert

影响范围：受影响的主要模块/包/服务（使用目录名称；若为跨模块变更，使用
```
monorepo
```
或
```
repo
```
）
是否为代码变更：如果PR修改了源代码（不仅是文档、markdown或仅配置文件变更），在创建PR前需执行步骤2中的本地验证清单。

2. Local Verification (for code changes)

2. 本地验证（针对代码变更）

Skip this step if the PR only touches documentation, markdown files, or other non-code files. For any change that touches source files, run your project's verification commands locally before creating the PR.

Discover the commands by reading the repo root (e.g.

Makefile

package.json

pyproject.toml

Cargo.toml

go.mod

build.gradle

mix.exs

Gemfile

composer.json

justfile

Taskfile.yml

README.md

, or the CI workflow config). Use filter/target flags where available (e.g.

turbo --filter

nx --projects

pnpm --filter

bazel //path/...

cargo -p <crate>

pytest <path>

go test ./<pkg>/...

) to run only the affected portions — it is faster than running the whole repo.

Common verification categories to run when applicable:

如果PR仅涉及文档、markdown文件或其他非代码文件，跳过此步骤。对于任何修改源码的变更，在创建PR前需本地运行项目的验证命令。

通过查看仓库根目录的文件（如

Makefile

、

package.json

、

pyproject.toml

、

Cargo.toml

、

go.mod

、

build.gradle

、

mix.exs

、

Gemfile

、

composer.json

、

justfile

、

Taskfile.yml

、

README.md

或CI工作流配置）找到对应命令。尽可能使用过滤/目标标志（如

turbo --filter

、

nx --projects

、

pnpm --filter

、

bazel //path/...

、

cargo -p <crate>

、

pytest <path>

、

go test ./<pkg>/...

）仅运行受影响部分——这比运行整个仓库更快。

适用时需运行的常见验证类别：

Typecheck / Compile

类型检查 / 编译

Run the project's static type check or compile step if it has one.

Examples across ecosystems (use whatever the repo defines):

TypeScript:

npm run typecheck

pnpm -r typecheck

tsc --noEmit

Python (typed):
```
mypy .
```
,
```
pyright
```
,
```
ty check
```
Rust:
```
cargo check
```
Go:
```
go build ./...
```
,
```
go vet ./...
```
Java/Kotlin:
```
./gradlew compileJava
```
,
```
./mvnw compile
```

如果项目支持，运行静态类型检查或编译步骤。

跨生态系统示例（使用仓库定义的命令）：

TypeScript:

npm run typecheck

pnpm -r typecheck

tsc --noEmit

Python（带类型）:
```
mypy .
```
,
```
pyright
```
,
```
ty check
```
Rust:
```
cargo check
```
Go:
```
go build ./...
```
,
```
go vet ./...
```
Java/Kotlin:
```
./gradlew compileJava
```
,
```
./mvnw compile
```

Lint / Format

代码检查 / 格式化

Run the project's linter and formatter. Prefer an autofix target if one exists.

Examples:

JS/TS:

npm run fix

npm run lint

eslint .

prettier --check .

Python:

ruff check --fix .

ruff format .

black .

flake8

Rust:

cargo clippy --all-targets

cargo fmt --check

Go:
```
golangci-lint run
```
,
```
gofmt -l .
```
Shell:
```
shellcheck
```
,
```
shfmt -d .
```

运行项目的代码检查器和格式化工具。如果有自动修复目标，优先使用。

示例：

JS/TS:

npm run fix

npm run lint

eslint .

prettier --check .

Python:

ruff check --fix .

ruff format .

black .

flake8

Rust:

cargo clippy --all-targets

cargo fmt --check

Go:
```
golangci-lint run
```
,
```
gofmt -l .
```
Shell:
```
shellcheck
```
,
```
shfmt -d .
```

Tests

测试

Run the unit/integration tests for affected packages.

Examples:

JS/TS:

npm run test -- --filter=<workspace>

pnpm -r test

vitest run <path>

jest <path>

Python:

pytest <path>

tox -e <env>

python -m unittest

Rust:
```
cargo test -p <crate>
```
Go:
```
go test ./<pkg>/...
```
Java/Kotlin:
```
./gradlew test
```
,
```
./mvnw test
```
Ruby:
```
bundle exec rspec <path>
```
,
```
rake test
```

运行受影响包的单元/集成测试。

示例：

JS/TS:

npm run test -- --filter=<workspace>

pnpm -r test

vitest run <path>

jest <path>

Python:

pytest <path>

tox -e <env>

python -m unittest

Rust:
```
cargo test -p <crate>
```
Go:
```
go test ./<pkg>/...
```
Java/Kotlin:
```
./gradlew test
```
,
```
./mvnw test
```
Ruby:
```
bundle exec rspec <path>
```
,
```
rake test
```

Additional checks (run when relevant)

额外检查（相关时运行）

Unused exports / dead code: Run your project's dead-code check if it has one (e.g.
```
knip
```
,
```
ts-prune
```
,
```
vulture
```
for Python,
```
deadcode
```
/
```
unused
```
for Go,
```
cargo udeps
```
for Rust).
Dependency hygiene: Run your project's dependency check if it has one (e.g.
```
depcheck
```
,
```
pip check
```
,
```
cargo audit
```
,
```
bundle audit
```
).
Lockfile in sync: If you modified any dependency manifest (
```
package.json
```
,
```
requirements.txt
```
,
```
pyproject.toml
```
,
```
Cargo.toml
```
,
```
go.mod
```
,
```
Gemfile
```
, etc.), run the install command (
```
npm install
```
,
```
pnpm install
```
,
```
uv sync
```
,
```
poetry lock --no-update
```
,
```
cargo update -w
```
,
```
go mod tidy
```
,
```
bundle install
```
) and commit any lockfile changes. CI commonly fails if the lockfile is out of date.
Generated code / codegen: If the repo has an OpenAPI spec, protobuf, GraphQL schema, SQL migrations, or any other generated artifacts, regenerate and commit any changes.
Style / asset linters: Run stylesheet linters (
```
stylelint
```
, etc.) or asset linters if you changed those files.
Security scans: Run any security/secret scanners configured in the repo (
```
trivy
```
,
```
semgrep
```
,
```
gitleaks
```
, etc.).

未使用导出 / 死代码：如果项目有死代码检查工具，运行对应命令（如
```
knip
```
、
```
ts-prune
```
、Python的
```
vulture
```
、Go的
```
deadcode
```
/
```
unused
```
、Rust的
```
cargo udeps
```
）。
依赖健康检查：如果项目有依赖检查工具，运行对应命令（如
```
depcheck
```
、
```
pip check
```
、
```
cargo audit
```
、
```
bundle audit
```
）。
锁文件同步：如果修改了任何依赖清单（
```
package.json
```
、
```
requirements.txt
```
、
```
pyproject.toml
```
、
```
Cargo.toml
```
、
```
go.mod
```
、
```
Gemfile
```
等），运行安装命令（
```
npm install
```
、
```
pnpm install
```
、
```
uv sync
```
、
```
poetry lock --no-update
```
、
```
cargo update -w
```
、
```
go mod tidy
```
、
```
bundle install
```
）并提交锁文件的变更。如果锁文件过期，CI通常会失败。
生成代码 / 代码生成：如果仓库包含OpenAPI规范、protobuf、GraphQL schema、SQL迁移或其他生成产物，重新生成并提交变更。
样式 / 资源检查器：如果修改了样式表或资源文件，运行对应检查器（如
```
stylelint
```
等）。
安全扫描：运行仓库中配置的安全/密钥扫描工具（如
```
trivy
```
、
```
semgrep
```
、
```
gitleaks
```
等）。

3. Link to a Ticket (optional)

3. 关联工单（可选）

If your org uses an issue tracker, ask the user whether to:

Create a new ticket: Use the appropriate tool (Linear, Jira, GitHub Issues, etc.)
Link an existing ticket: Ask for the identifier (e.g.
```
TEAM-1234
```
,
```
JIRA-567
```
,
```
#42
```
)
Skip: Only if user explicitly says no ticket is needed

Most CI systems can be configured to require the ticket identifier in the PR body. Follow your org's convention.

如果你的组织使用问题跟踪系统，询问用户是否需要：

创建新工单：使用合适的工具（Linear、Jira、GitHub Issues等）
关联现有工单：询问工单标识符（如
```
TEAM-1234
```
、
```
JIRA-567
```
、
```
#42
```
）
跳过：仅当用户明确表示无需工单时使用

大多数CI系统可配置为要求PR正文中包含工单标识符，请遵循组织的规范。

4. Format PR Title

4. 格式化PR标题

Follow Conventional Commits:

type(scope): description

type

feat

fix

docs

refactor

test

chore

perf

ci

build

revert

```
scope
```
: Name of the affected module/package/service/directory, or
```
monorepo
```
/
```
repo
```
for cross-cutting changes. Multiple scopes can be comma-separated:
```
fix(a, b, c): ...
```

Examples:

```
feat(web): add dark mode toggle
```

fix(cli, daemon): load shell env at entrypoint

fix(api): handle nil response from upstream

```
chore(repo): bump dependencies
```

遵循Conventional Commits格式：

type(scope): description

type

：

feat

、

fix

、

docs

、

refactor

、

test

、

chore

、

perf

、

ci

、

build

、

revert

```
scope
```
：受影响模块/包/服务/目录的名称；若为跨模块变更，使用
```
monorepo
```
或
```
repo
```
。多个范围可逗号分隔：
```
fix(a, b, c): ...
```

示例：

```
feat(web): add dark mode toggle
```

fix(cli, daemon): load shell env at entrypoint

fix(api): handle nil response from upstream

```
chore(repo): bump dependencies
```

5. Generate PR Body

5. 生成PR正文

Fill in all sections from your PR template. A typical template has four sections:

markdown

undefined

填写PR模板的所有部分。典型模板包含四个部分：

markdown

undefined

Description

Related Issue

Closes TEAM-XXXX

Closes TEAM-XXXX

Potential Risk & Impact

How Has This Been Tested?

undefined

undefined

6. Create the PR

6. 创建PR

bash

gh pr create \
  --base <base-branch> \
  --head <branch-name> \
  --title "<type>(<scope>): <description>" \
  --body "<generated body>"

If the body is long, write it to a temp file and use

--body-file

bash

gh pr create --base <base-branch> --head <branch> --title "..." --body-file /tmp/pr-body.md

bash

gh pr create \
  --base <base-branch> \
  --head <branch-name> \
  --title "<type>(<scope>): <description>" \
  --body "<generated body>"

如果正文较长，可写入临时文件并使用

--body-file

：

bash

gh pr create --base <base-branch> --head <branch> --title "..." --body-file /tmp/pr-body.md

7. Report Result

7. 反馈结果

Return the PR URL to the user.

将PR URL返回给用户。

CI Checks Reference (template)

CI检查参考（模板）

These are typical check categories that run on every PR. Map them to your repo's actual commands when adapting this skill.

以下是每个PR通常会运行的检查类别。调整此技能时，请映射到仓库的实际命令。

Always-run checks

必运行检查

Category	What it does	How to find the local command
Typecheck / compile	Verifies the project compiles or passes static types	Check `package.json` , `Makefile` , `pyproject.toml` , `Cargo.toml` , `go.mod` , CI config
Lint	Enforces code style / correctness rules	Check for `lint` , `check` , or equivalent scripts in the repo root
Format	Enforces consistent formatting	Check for `format` , `fmt` , `prettier` , `black` , `gofmt` , `rustfmt` , etc.
Tests	Runs unit and integration tests	Check for `test` script / target
Dead code / unused exports	Flags unused code	Check for `knip` , `ts-prune` , `vulture` , `cargo udeps` , etc.
Dependency check	Flags unused / vulnerable dependencies	Check for `depcheck` , `audit` , `cargo audit` , etc.
Lockfile in sync	Fails if lockfile is stale relative to the manifest	Run your package manager's install command and commit the lockfile
PR Conventions	Validates branch name, semantic title, ticket presence	Follow the formatting rules above

类别	功能	如何找到本地命令
类型检查 / 编译	验证项目可编译或通过静态类型检查	查看 `package.json` 、 `Makefile` 、 `pyproject.toml` 、 `Cargo.toml` 、 `go.mod` 、CI配置
代码检查	强制执行代码风格/正确性规则	查看仓库根目录中的 `lint` 、 `check` 或等效脚本
格式化	强制执行一致的代码格式	查看 `format` 、 `fmt` 、 `prettier` 、 `black` 、 `gofmt` 、 `rustfmt` 等相关配置
测试	运行单元和集成测试	查看 `test` 脚本/目标
死代码 / 未使用导出	标记未使用的代码	查看 `knip` 、 `ts-prune` 、 `vulture` 、 `cargo udeps` 等工具
依赖检查	标记未使用/易受攻击的依赖	查看 `depcheck` 、 `audit` 、 `cargo audit` 等工具
锁文件同步	若锁文件相对于清单过期则失败	运行包管理器的安装命令并提交锁文件
PR规范	验证分支名称、语义化标题、工单存在性	遵循上述格式化规则

Conditional checks (run only when affected files change)

条件检查（仅当受影响文件变更时运行）

API / schema validation: Triggered by API or schema changes. Regenerate locally.
Platform-specific builds: Triggered when desktop/mobile/embedded targets are affected.
E2E tests: Triggered when the consumer app or top-level binary is affected.

API / Schema验证：由API或Schema变更触发。需本地重新生成。
特定平台构建：当桌面/移动/嵌入式目标受影响时触发。
E2E测试：当消费者应用或顶层二进制文件受影响时触发。

Typical PR conventions CI enforces

CI通常强制执行的PR规范

Branch name: Max length, allowed characters (e.g.
```
[A-Za-z0-9/-]
```
).
Title: Conventional Commits format with a valid scope.
Ticket reference: PR body must contain a ticket identifier (often skipped for
```
chore:
```
and
```
revert:
```
types).

分支名称：最大长度、允许的字符（如
```
[A-Za-z0-9/-]
```
）。
标题：符合Conventional Commits格式且包含有效范围。
工单引用：PR正文必须包含工单标识符（
```
chore:
```
和
```
revert:
```
类型通常可跳过）。

Common Mistakes to Avoid

需避免的常见错误

Wrong base branch: Use the branch your org takes PRs into (e.g.
```
dev
```
,
```
main
```
,
```
develop
```
,
```
trunk
```
).
Missing scope: PR title CI check often requires a valid scope.
Missing ticket reference: Description must reference your ticket ID for CI to pass (except
```
chore:
```
/
```
revert:
```
).
Forgetting to push: Branch must be on remote before
```
gh pr create
```
.
Lockfile drift: Always run the install command and commit lockfile changes after dependency changes.
Skipping local checks on code PRs: Typecheck/compile, lint, and tests should be run locally before sending out code changes to catch issues early and avoid CI round-trips.
Uncommitted generated artifacts: After API/schema changes, regenerate and commit.

基准分支错误：使用组织接受PR的分支（如
```
dev
```
、
```
main
```
、
```
develop
```
、
```
trunk
```
）。
缺少范围：PR标题的CI检查通常要求包含有效范围。
缺少工单引用：描述必须包含工单ID才能通过CI检查（
```
chore:
```
/
```
revert:
```
类型除外）。
忘记推送分支：执行
```
gh pr create
```
前需将分支推送到远程仓库。
锁文件不一致：修改依赖后务必运行安装命令并提交锁文件变更。
代码PR跳过本地检查：代码变更发送前需本地运行类型检查/编译、代码检查和测试，提前发现问题并避免CI往返。
未提交生成产物：API/Schema变更后需重新生成并提交产物。