Back to Details

pr-writer

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

PR Writer

PR Writer

Create pull requests following Sentry's engineering practices.
Requires: GitHub CLI (
gh
) authenticated and available.
遵循Sentry的工程实践创建pull request。
依赖：已完成身份认证且可用的GitHub CLI (
gh
)

Prerequisites

前置条件

Before creating a PR, ensure all changes are committed. If there are uncommitted changes, run the 
sentry-skills:commit
skill first to commit them properly.
bash
undefined
创建PR前，请确保所有变更都已提交。如果存在未提交的变更，请先运行
sentry-skills:commit
skill完成规范提交。
bash
undefined

Check for uncommitted changes

检查未提交的变更

git status --porcelain

If the output shows any uncommitted changes (modified, added, or untracked files that should be included), invoke the `sentry-skills:commit` skill before proceeding.
git status --porcelain

如果输出显示存在任何未提交的变更（需要纳入的修改、新增或未跟踪文件），请先调用`sentry-skills:commit` skill再继续后续操作。

Process

操作流程

Step 1: Verify Branch State

步骤1：验证分支状态

bash
undefined
bash
undefined

Detect the default branch — note the output for use in subsequent commands

检测默认分支 —— 保存输出结果用于后续命令

gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name'

```bash
gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name'

```bash

Check current branch and status (substitute the detected branch name above for BASE)

检查当前分支和状态（将上一步检测到的分支名替换为BASE）

git status git log BASE..HEAD --oneline

Ensure:
- All changes are committed
- Branch is up to date with remote
- Changes are rebased on the base branch if needed
git status git log BASE..HEAD --oneline

请确保：
- 所有变更都已提交
- 分支与远端保持同步
- 如有需要，变更已基于基分支完成变基

Step 2: Analyze Changes

步骤2：分析变更

Review what will be included in the PR:
bash
undefined
检查PR将包含的内容：
bash
undefined

See all commits that will be in the PR (substitute detected branch name for BASE)

查看PR包含的所有提交（将检测到的分支名替换为BASE）

git log BASE..HEAD
git log BASE..HEAD

See the full diff

查看完整diff

git diff BASE...HEAD

Understand the scope and purpose of all changes before writing the description.
git diff BASE...HEAD

撰写描述前请明确所有变更的范围和目的。

Step 3: Write the PR Description

步骤3：撰写PR描述

Use this structure for PR descriptions (ignoring any repository PR templates):
markdown
<brief description of what the PR does>

<why these changes are being made - the motivation>

<alternative approaches considered, if any>

<any additional context reviewers need>
Do NOT include:
  • "Test plan" sections
  • Checkbox lists of testing steps
  • Redundant summaries of the diff
Do include:
  • Clear explanation of what and why
  • Links to relevant issues or tickets
  • Context that isn't obvious from the code
  • Notes on specific areas that need careful review
PR描述请使用以下结构（无需遵循代码仓库的PR模板）：
markdown
<PR实现功能的简要描述>

<做出这些变更的原因 —— 背景动机>

<考虑过的其他可选方案（如有）>

<评审人需要了解的其他补充上下文>
禁止包含：
  • "Test plan"章节
  • 测试步骤的勾选列表
  • 冗余的diff摘要
必须包含：
  • 对变更内容和背景的清晰说明
  • 相关issue或工单的链接
  • 从代码中无法直观看出的上下文信息
  • 需要重点评审的特定区域说明

Step 4: Create the PR

步骤4：创建PR

bash
gh pr create --draft --title "<type>(<scope>): <description>" --body "$(cat <<'EOF'
<description body here>
EOF
)"
Title format follows commit conventions:
  • feat(scope): Add new feature
  • fix(scope): Fix the bug
  • ref: Refactor something
bash
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 Description Examples

PR描述示例

Feature PR

功能PR

markdown
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
markdown
Add Slack thread replies for alert notifications

当告警被更新或解决时，我们现在会在原始Slack线程中发布回复，而非创建新消息。这可以将相关通知归类到一起，减少频道消息噪音。

此前我们考虑过编辑原始消息，但线程模式可以更好地保留事件时间线，且在原始消息超出Slack编辑窗口时依然可用。

Refs SENTRY-1234

Bug Fix PR

Bug修复PR

markdown
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
markdown
Handle null response in user API endpoint

软删除的账号会导致用户接口返回null，访问用户属性时会造成仪表盘崩溃。本次修改新增了空值检查，并返回正确的404响应。

该问题在排查SENTRY-5678时发现。

Fixes SENTRY-5678

Refactor PR

重构PR

markdown
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.
markdown
Extract validation logic to shared module

将告警、issue和项目接口中的重复校验代码迁移到共享校验器类中，无行为变更。

这为后续在SENTRY-9999中新增校验规则做准备，避免在多个接口中重复实现逻辑。

Issue References

Issue关联规则

Reference issues in the PR body:
SyntaxEffect
Fixes #1234
Closes GitHub issue on merge
Fixes SENTRY-1234
Closes Sentry issue
Refs GH-1234
Links without closing
Refs LINEAR-ABC-123
Links Linear issue
在PR正文中按以下语法关联issue：
语法效果
Fixes #1234
合并PR时关闭对应的GitHub issue
Fixes SENTRY-1234
关闭对应的Sentry issue
Refs GH-1234
关联但不关闭issue
Refs LINEAR-ABC-123
关联Linear工单

Guidelines

指引

  • One PR per feature/fix - Don't bundle unrelated changes
  • Keep PRs reviewable - Smaller PRs get faster, better reviews
  • Explain the why - Code shows what; description explains why
  • Mark WIP early - Use draft PRs for early feedback
  • 每个PR对应一个功能/修复 —— 不要将不相关的变更打包到同一个PR
  • 保持PR易于评审 —— 更小的PR会得到更快、质量更高的评审反馈
  • 说明变更原因 —— 代码展示了做了什么，描述需要说明为什么这么做
  • 尽早标记WIP —— 使用草稿PR获取早期反馈

Editing Existing PRs

编辑现有PR

If you need to update a PR after creation, use 
gh api
instead of 
gh pr edit
:
bash
undefined
如果你需要在PR创建后更新它，请使用
gh api
而非
gh pr edit
：
bash
undefined

Update PR description

更新PR描述

gh api -X PATCH repos/{owner}/{repo}/pulls/PR_NUMBER -f body="$(cat <<'EOF' Updated description here EOF )"
gh api -X PATCH repos/{owner}/{repo}/pulls/PR_NUMBER -f body="$(cat <<'EOF' 此处填写更新后的描述 EOF )"

Update PR title

更新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 here'

Update both

同时更新两者

gh api -X PATCH repos/{owner}/{repo}/pulls/PR_NUMBER
-f title='new: Title'
-f body='New description'

Note: `gh pr edit` is currently broken due to GitHub's Projects (classic) deprecation.
gh api -X PATCH repos/{owner}/{repo}/pulls/PR_NUMBER
-f title='new: Title'
-f body='New description'

注意：由于GitHub Projects（经典版）下线，`gh pr edit`当前存在功能异常。

References

参考