creating-pull-requests

创建 pull request

在用户批准后，在 GitHub 上创建一个带有相应标签的草稿 PR。

关键约束：

• 在运行 gh pr create 之前，必须等待用户批准
• 在创建之前，必须在聊天中展示完整的 PR 内容
• 必须遵循下面的撰写和标签规则

步骤 1：选择模式

始终先询问用户：

你希望如何创建 PR？

1. 已就绪：我有一个功能分支，所有更改都已提交并推送
2. 自动化：自动处理分支创建、提交和推送

在继续之前等待用户回复。

步骤 2：执行 git 工作流

模式 A：已就绪

验证就绪状态：

git branch --show-current
git status
git branch -r | grep $(git branch --show-current)

与用户确认，然后继续步骤 3。

模式 B：自动化

假定用户已使用 git add 暂存更改。

git status
git checkout develop
git checkout -b {type}/{descriptive-name}
git commit -m "{imperative-verb} {what} {where}"
git push --set-upstream origin $(git branch --show-current)

分支命名： 采用 kebab-case 的 {type}/{brief-description}。 类型：feature、fix、refactor、chore、docs。 示例：feature/add-height-plotly-charts、fix/dataframe-memory-leak-scrolling。

提交信息： <imperative verb> <what> <where>，≤50 个字符，无句号。 示例：Add height parameter to plotly charts、Fix memory leak in dataframe scrolling。

步骤 3：撰写并创建 PR

在下面起草标题和描述时，请遵循 /reviewing-pr-description skill 中的标题/描述指南，使它们从一开始就清晰简洁。

3.1 确定标签

所有 PR 都需要这些标签：

类别	选项
Impact	impact:users（影响用户行为）或 impact:internal（不改变用户行为）
Change type	change:feature、change:bugfix、change:chore、change:refactor、change:docs、change:spec、change:other

注意： 标记为 change:spec 的 PR（仅用于规范/设计文档）不受 impact:* 要求约束。不要将 change:spec 用于包含代码更改的 PR。

3.2 生成 PR 标题

格式：[type] Description of change，≤63 个字符（适配 squash-merge 提交主题）。

示例：[feature] Add height parameter to plotly charts、[fix] Extra padding on button。

3.3 撰写 PR 描述

阅读 .github/pull_request_template.md 了解所需的部分，然后填写它们。

撰写规则：

• 突出重点。省略显而易见的内容。
• 列出更改时最多使用 2-4 个项目符号。
• 不要写元评论（"This PR..."、"We have..."、"I added..."）。直接说明更改了什么。
• 不要列出：添加测试、更新类型、添加验证、修复 linting（这些都是显而易见的）。
• 要解释非显而易见的决策（弃用、单位选择、回退行为）。

好：

使用 Height 类型系统为 st.plotly_chart() 添加 height 参数。

• 弃用 use_container_height（2025-12-31 之后移除）

差（列出每一项更改）：

• 在签名中添加了 height 参数
• 更新了布局配置 dataclass
• 添加了 height 值的验证
• 添加了单元测试

测试部分 — 根据更改的文件检测：

模式	测试类型
lib/tests/**/*.py	Python 单元测试
frontend/**/*.test.{ts,tsx}	前端单元测试
e2e_playwright/**/*_test.py	E2E 测试

勾选 PR 模板中匹配的复选框。如果没有更改测试文件，请解释原因。将 "manual testing" 保持未勾选（由用户填写）。

3.4 撰写 PR 供用户审阅

将完整的 PR 详情写入 work-tmp/pr_description.md：

---
title: [PR title from 3.2]
labels: impact:{users|internal}, change:{type}
---

[PR description from 3.3]

询问用户："我已将 PR 详情写入 work-tmp/pr_description.md。你可以直接在该文件中编辑标题、标签或描述。准备好创建 PR 时回复 'yes'，或提供反馈以进行更改。"

3.5 创建 PR（仅在用户批准后）

阅读 work-tmp/pr_description.md 以获取（可能已被编辑的）标题、标签和描述：

# Parse frontmatter from the reviewed file
title=$(grep '^title:' work-tmp/pr_description.md | sed 's/^title: //')
labels=$(grep '^labels:' work-tmp/pr_description.md | sed 's/^labels: //' | sed 's/, /,/g')

# Extract body (everything after the closing --- of frontmatter)
awk '/^---$/{if(++count==2) flag=1; next} flag' work-tmp/pr_description.md > work-tmp/pr_body.md

# Create PR using parsed values
gh pr create \
  --title "$title" \
  --body-file work-tmp/pr_body.md \
  --base develop \
  --label "$labels" \
  --draft

# Clean up temporary files
rm work-tmp/pr_description.md work-tmp/pr_body.md

参考

有关撰写原则、标签、分支命名和测试计划的完整详情，请参阅 Pull requests wiki。