create-pr

创建 Pull Request

遵循最佳工程实践创建 Pull Request。

需要：已完成身份验证且可用的 GitHub CLI (gh)。

前置条件

创建 PR 前，请确保所有更改都已提交。如果存在未提交的更改，请先运行提交技能 skill({ name: "conventional-commit" })，以规范地提交这些更改。

# Check for uncommitted changes
git status --porcelain

如果输出显示存在任何应纳入 PR 的未提交更改（已修改、已添加或未跟踪的文件），请先调用提交技能 skill({ name: "conventional-commit" })，然后再继续。

流程

第 1 步：检查分支状态

# Detect the default branch
BASE=$(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name')

# Check current branch and status
git status
git log $BASE..HEAD --oneline

确保：

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

第 2 步：分析更改

检查 PR 将包含的内容：

# See all commits that will be in the PR
git log $BASE..HEAD

# See the full diff
git diff $BASE...HEAD

在撰写说明之前，了解所有更改的范围和目的。

第 3 步：撰写 PR 说明

撰写 PR 说明时使用以下结构（忽略仓库中的 PR 模板）：

<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>

不要包含：

• “测试计划”部分
• 测试步骤复选框列表
• 对差异的冗余总结

应包含：

• 对做了什么以及为什么这样做的清晰说明
• 相关问题或工单的链接（仅在有链接时）
• 代码中不明显的背景信息
• 需要仔细审查的特定部分说明

第 4 步：创建 PR

gh pr create --title "<type>(<scope>): <description>" --body "
<description body here>
"

标题格式遵循提交规范：

• feat(scope): Add new feature
• fix(scope): Fix the bug
• refactor(scope): 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.

错误修复 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.

重构 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 without
duplicating logic across endpoints.

指南

• 每个功能或修复对应一个 PR——不要捆绑无关的更改
• 让 PR 易于审查——较小的 PR 能获得更快、更高质量的审查
• 说明原因——代码展示了做什么；说明解释了为什么

编辑现有 PR

创建 PR 后更新时，该技能会根据你的 GitHub CLI 版本自动选择最佳方式：

• gh 2.82.1+：使用原生 gh pr edit（简洁且功能齐全）
• gh < 2.82.1：回退到 gh api（避免 Projects classic 弃用错误）

检查你的版本

# Check GitHub CLI version
gh --version

现代方式（gh 2.82.1+）

# Update PR description
gh pr edit PR_NUMBER --body "Updated description here"

# Update PR title
gh pr edit PR_NUMBER --title "New Title here"

# Update both
gh pr edit PR_NUMBER --title "new: Title" --body "New description"

旧版回退方式（gh < 2.82.1）

如果 gh pr edit 因“Projects (classic) is being deprecated”错误而失败，请直接使用 API：

# Update PR description
gh api -X PATCH repos/{owner}/{repo}/pulls/PR_NUMBER -f body="
Updated description here
"

# Update PR title
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'

注意：Projects (classic) 错误已在 gh 2.82.1 中修复（2025 年 10 月）。 如果你使用的是较旧版本，请通过包管理器升级。