---

name: pr-writer description: "按照 Sentry 工程实践创建 Pull Request。" risk: unknown source: community

PR 编写器

按照 Sentry 工程实践创建 Pull Request。

前提条件：GitHub CLI（gh）已认证且可用。

何时使用

• 你准备好打开一个 Pull Request，需要基于已提交分支的 diff 生成结构化描述。
• 你希望 PR 正文能说明改了什么、为什么改、以及审查者需要的上下文。
• 你正在使用 GitHub CLI，需要一个可重复的 PR 编写工作流，而不是临时编写描述。

前置条件

创建 PR 前，确保所有更改已提交。如果有未提交的更改，请先运行 sentry-skills:commit 技能来正确提交。

# 检查未提交的更改
git status --porcelain

如果输出显示任何未提交的更改（已修改、已添加或应包含的未跟踪文件），请在继续之前调用 sentry-skills:commit 技能。

流程

步骤 1：验证分支状态

# 检测默认分支 — 记录输出以在后续命令中使用
gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name'

# 检查当前分支和状态（将检测到的分支名替换上面的 BASE）
git status
git log BASE..HEAD --oneline

确保：

• 所有更改已提交
• 分支与远程保持同步
• 如需要，更改已 rebase 到基础分支

步骤 2：分析更改

审查将包含在 PR 中的内容：

# 查看 PR 中将包含的所有提交（将检测到的分支名替换 BASE）
git log BASE..HEAD

# 查看完整 diff
git diff BASE...HEAD

在编写描述之前，理解所有更改的范围和目的。

步骤 3：编写 PR 描述

使用以下结构编写 PR 描述（忽略任何仓库 PR 模板）：

<PR 做了什么的简要描述>

<为什么要做这些更改 - 动机>

<考虑过的替代方案（如有）>

<审查者需要的额外上下文>

不要包含：

• "测试计划"部分
• 测试步骤的复选框列表
• diff 的冗余摘要

应该包含：

• 清晰说明做了什么和为什么
• 相关 issue 或工单的链接
• 代码中不明显的上下文
• 需要仔细审查的特定区域说明

步骤 4：创建 PR

gh pr create --draft --title "<type>(<scope>): <description>" --body "$(cat <<'EOF'
<描述正文>
EOF
)"

标题格式遵循提交约定：

• feat(scope): Add new feature
• fix(scope): Fix the bug
• ref: Refactor something

PR 描述示例

功能 PR

Add Slack thread replies for alert notifications

When an alert is updated or resolved, we now post a reply to the original
Slack thread instead of creating a new message. This keeps related
notifications grouped and reduces channel noise.

Previously considered posting edits to the original message, but threading
better preserves the timeline of events and works when the original message
is older than Slack's edit window.

Refs SENTRY-1234

Bug 修复 PR

Handle null response in user API endpoint

The user endpoint could return null for soft-deleted accounts, causing
dashboard crashes when accessing user properties. This adds a null check
and returns a proper 404 response.

Found while investigating SENTRY-5678.

Fixes SENTRY-5678

重构 PR

Extract validation logic to shared module

Moves duplicate validation code from the alerts, issues, and projects
endpoints into a shared validator class. No behavior change.

This prepares for adding new validation rules in SENTRY-9999 without
duplicating logic across endpoints.

Issue 引用

在 PR 正文中引用 issue：

| 语法 | 效果 | |------|------| | Fixes #1234 | 合并时关闭 GitHub issue | | Fixes SENTRY-1234 | 关闭 Sentry issue | | Refs GH-1234 | 链接但不关闭 | | Refs LINEAR-ABC-123 | 链接 Linear issue |

指导原则

• 每个 PR 一个功能/修复 - 不要捆绑不相关的更改
• 保持 PR 可审查 - 较小的 PR 能获得更快、更好的审查
• 解释原因 - 代码展示了做什么；描述解释为什么
• 尽早标记 WIP - 使用草稿 PR 获取早期反馈

编辑现有 PR

如果需要在创建后更新 PR，使用 gh api 而不是 gh pr edit：

# 更新 PR 描述
gh api -X PATCH repos/{owner}/{repo}/pulls/PR_NUMBER -f body="$(cat <<'EOF'
Updated description here
EOF
)"

# 更新 PR 标题
gh api -X PATCH repos/{owner}/{repo}/pulls/PR_NUMBER -f title='new: Title here'

# 同时更新两者
gh api -X PATCH repos/{owner}/{repo}/pulls/PR_NUMBER \
  -f title='new: Title' \
  -f body='New description'

注意：由于 GitHub 的 Projects（经典版）弃用，gh pr edit 目前存在问题。

参考资料

• Sentry 代码审查指南