Back to Details

create-pull-request

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Create Pull Request

创建Pull Request

This skill guides you through creating a well-structured GitHub pull request that follows project conventions and best practices.
本技能将引导你创建符合项目规范和最佳实践的结构清晰的GitHub Pull Request。

Prerequisites Check

前置条件检查

Before proceeding, verify the following:
在开始之前，请验证以下内容：

1. Check if 
gh
CLI is installed

1. 检查是否已安装
gh
CLI

bash
gh --version
If not installed, inform the user:
The GitHub CLI (
gh
) is required but not installed. Please install it:
bash
gh --version
如果未安装，请告知用户：
GitHub CLI（
gh
）为必需工具但未安装。请进行安装：

2. Check if authenticated with GitHub

2. 检查是否已通过GitHub认证

bash
gh auth status
If not authenticated, guide the user to run 
gh auth login
.
bash
gh auth status
如果未认证，请引导用户运行
gh auth login
。

3. Verify clean working directory

3. 验证工作目录是否干净

bash
git status
If there are uncommitted changes, ask the user whether to:
  • Commit them as part of this PR
  • Stash them temporarily
  • Discard them (with caution)
bash
git status
如果存在未提交的变更，请询问用户选择以下操作：
  • 将它们作为本次PR的一部分提交
  • 暂时储藏它们
  • 丢弃它们（请谨慎操作）

Gather Context

收集上下文信息

1. Identify the current branch

1. 识别当前分支

bash
git branch --show-current
Ensure you're not on 
main
or 
master
. If so, ask the user to create or switch to a feature branch.
bash
git branch --show-current
确保你不在
main
或
master
分支上。如果是，请询问用户创建或切换到功能分支。

2. Find the base branch

2. 找到基础分支

bash
git remote show origin | grep "HEAD branch"
This is typically 
main
or 
master
.
bash
git remote show origin | grep "HEAD branch"
基础分支通常是
main
或
master
。

3. Analyze recent commits relevant to this PR

3. 分析与本次PR相关的近期提交

bash
git log origin/main..HEAD --oneline --no-decorate
Review these commits to understand:
  • What changes are being introduced
  • The scope of the PR (single feature/fix or multiple changes)
  • Whether commits should be squashed or reorganized
bash
git log origin/main..HEAD --oneline --no-decorate
查看这些提交以了解：
  • 引入了哪些变更
  • PR的范围（单个功能/修复或多个变更）
  • 是否需要压缩或重新整理提交

4. Review the diff

4. 查看差异

bash
git diff origin/main..HEAD --stat
This shows which files changed and helps identify the type of change.
bash
git diff origin/main..HEAD --stat
这会显示哪些文件被修改，有助于识别变更类型。

Information Gathering

信息收集

Before creating the PR, you need the following information. Check if it can be inferred from:
  • Commit messages
  • Branch name (e.g., 
    fix/issue-123
    , 
    feature/new-login
    )
  • Changed files and their content
If any critical information is missing, use 
ask_followup_question
to ask the user:
在创建PR之前，你需要以下信息。检查是否可以从以下来源推断：
  • 提交消息
  • 分支名称（例如
    fix/issue-123
    、
    feature/new-login
    ）
  • 修改的文件及其内容
如果缺少关键信息，请使用
ask_followup_question
询问用户：

Required Information

必填信息

  1. Related Issue Number: Look for patterns like 
    #123
    , 
    fixes #123
    , or 
    closes #123
    in commit messages
  2. Description: What problem does this solve? Why were these changes made?
  3. Type of Change: Bug fix, new feature, breaking change, refactor, cosmetic, documentation, or workflow
  4. Test Procedure: How was this tested? What could break?
  1. 相关Issue编号：在提交消息中查找类似
    #123
    、
    fixes #123
    或
    closes #123
    的格式
  2. 描述：本次变更解决了什么问题？为什么进行这些变更？
  3. 变更类型：Bug修复、新功能、破坏性变更、重构、外观调整、文档更新或工作流变更
  4. 测试流程：如何测试本次变更？可能会有哪些部分受影响？

Example clarifying question

示例澄清问题

If the issue number is not found:
I couldn't find a related issue number in the commit messages or branch name. What GitHub issue does this PR address? (Enter the issue number, e.g., "123" or "N/A" for small fixes)
如果未找到Issue编号：
我在提交消息或分支名称中未找到相关Issue编号。本次PR对应的GitHub Issue是什么？（请输入Issue编号，例如"123"，小修复可输入"N/A"）

Git Best Practices

Git最佳实践

Before creating the PR, consider these best practices:
在创建PR之前，请考虑以下最佳实践：

Commit Hygiene

提交规范

  1. Atomic commits: Each commit should represent a single logical change
  2. Clear commit messages: Follow conventional commit format when possible
  3. No merge commits: Prefer rebasing over merging to keep history clean
  1. 原子提交：每个提交应代表一个独立的逻辑变更
  2. 清晰的提交消息：尽可能遵循约定式提交格式
  3. 无合并提交：优先使用变基而非合并以保持历史记录整洁

Branch Management

分支管理

  1. Rebase on latest main (if needed):
    bash
    git fetch origin
git rebase origin/main
  2. Squash if appropriate: If there are many small "WIP" commits, consider interactive rebase:
    bash
    git rebase -i origin/main
    Only suggest this if commits appear messy and the user is comfortable with rebasing.
  1. 基于最新main分支变基（如有需要）：
    bash
    git fetch origin
git rebase origin/main
  2. 适当压缩提交：如果存在许多小型的"WIP"（进行中）提交，考虑使用交互式变基：
    bash
    git rebase -i origin/main
    仅当提交记录混乱且用户熟悉变基操作时才建议此操作。

Push Changes

推送变更

Ensure all commits are pushed:
bash
git push origin HEAD
If the branch was rebased, you may need:
bash
git push origin HEAD --force-with-lease
确保所有提交已推送：
bash
git push origin HEAD
如果分支已变基，可能需要执行：
bash
git push origin HEAD --force-with-lease

Create the Pull Request

创建Pull Request

IMPORTANT: Read and use the PR template at 
.github/pull_request_template.md
. The PR body format must strictly match the template structure. Do not deviate from the template format.
When filling out the template:
  • Replace 
    #XXXX
    with the actual issue number, or keep as 
    #XXXX
    if no issue exists (for small fixes)
  • Fill in all sections with relevant information gathered from commits and context
  • Mark the appropriate "Type of Change" checkbox(es)
  • Complete the "Pre-flight Checklist" items that apply
重要提示：请阅读并使用
.github/pull_request_template.md
中的PR模板。PR正文格式必须严格匹配模板结构，请勿偏离模板格式。
填写模板时：
  • 将
    #XXXX
    替换为实际Issue编号，若无Issue则保留
    #XXXX
    （适用于小型修复）
  • 使用从提交和上下文收集到的相关信息填写所有章节
  • 勾选对应的“变更类型”复选框
  • 完成适用的“飞行前检查”项

Create PR with gh CLI

通过gh CLI创建PR

bash
gh pr create --title "PR_TITLE" --body "PR_BODY" --base main
Alternatively, create as draft if the user wants review before marking ready:
bash
gh pr create --title "PR_TITLE" --body "PR_BODY" --base main --draft
bash
gh pr create --title "PR_TITLE" --body "PR_BODY" --base main
或者，如果用户希望先获得审核再标记为就绪，可创建草稿PR：
bash
gh pr create --title "PR_TITLE" --body "PR_BODY" --base main --draft

Post-Creation

创建后操作

After creating the PR:
  1. Display the PR URL so the user can review it
  2. Remind about CI checks: Tests and linting will run automatically
  3. Suggest next steps:
    • Add reviewers if needed: 
      gh pr edit --add-reviewer USERNAME
    • Add labels if needed: 
      gh pr edit --add-label "bug"
创建PR后：
  1. 显示PR链接以便用户查看
  2. 提醒CI检查：测试和代码检查将自动运行
  3. 建议后续步骤：
    • 如需添加审核者：
      gh pr edit --add-reviewer USERNAME
    • 如需添加标签：
      gh pr edit --add-label "bug"

Error Handling

错误处理

Common Issues

常见问题

  1. No commits ahead of main: The branch has no changes to submit
    • Ask if the user meant to work on a different branch
  2. Branch not pushed: Remote doesn't have the branch
    • Push the branch first: 
      git push -u origin HEAD
  3. PR already exists: A PR for this branch already exists
    • Show the existing PR: 
      gh pr view
    • Ask if they want to update it instead
  4. Merge conflicts: Branch conflicts with base
    • Guide user through resolving conflicts or rebasing
  1. 没有领先于main分支的提交：当前分支没有可提交的变更
    • 询问用户是否打算在其他分支上工作
  2. 分支未推送：远程仓库中不存在该分支
    • 先推送分支：
      git push -u origin HEAD
  3. PR已存在：该分支对应的PR已存在
    • 显示现有PR：
      gh pr view
    • 询问用户是否要更新现有PR
  4. 合并冲突：分支与基础分支存在冲突
    • 引导用户解决冲突或重新变基

Summary Checklist

总结检查清单

Before finalizing, ensure:
  • gh
    CLI is installed and authenticated
  • Working directory is clean
  • All commits are pushed
  • Branch is up-to-date with base branch
  • Related issue number is identified, or placeholder is used
  • PR description follows the template exactly
  • Appropriate type of change is selected
  • Pre-flight checklist items are addressed
最终确认前，请确保：
  • gh
    CLI已安装并完成认证
  • 工作目录干净
  • 所有提交已推送
  • 分支已与基础分支保持同步
  • 已识别相关Issue编号，或已使用占位符
  • PR描述完全遵循模板格式
  • 已选择合适的变更类型
  • 已处理飞行前检查项