create-pr

create-pr

概述

本指南介绍在 warp 仓库中创建拉取请求的最佳实践，包括合并 master、高效验证更改、关联 Linear 任务、确保测试覆盖充分，以及合理组织 PR 以便评审。

相关技能

• write-pr-description - 编写 PR 正文：模板章节、文案和评审者指南
• fix-errors - 在创建 PR 前修复指定的编译、测试、Lint 或格式问题
• warp-integration-test - 为用户可见的流程、回归问题和 P0 用例添加或更新集成测试覆盖
• add-feature-flag - 使用功能标志控制更改

PR 前检查清单

1. 将 master 合并到功能分支

开始评审流程前，务必将 master 合并到功能分支。

git fetch origin
git merge origin/master

创建 PR 前，请在本地解决所有合并冲突。

2. 检查更改

创建 PR 前，请检查准备提交的更改：

# View commits in your branch (comparing against base branch)
git --no-pager log <base-branch>..HEAD --oneline

# View file statistics for changes
git --no-pager diff <base-branch>...HEAD --stat

# View full diff
git --no-pager diff <base-branch>...HEAD

这有助于你：

• 确认所有预期的更改都已包含
• 在评审前发现意外更改
• 准确撰写 PR 描述
• 确保对比的是正确的基准分支
• 测试： 按需添加测试——修复 Bug（回归测试）、算法代码（单元测试）、UI 组件（布局测试）、P0 用例（集成测试）。请参阅下方的测试要求。

3. 遵循实现 Agent 的验证结果

创建 PR 并不代表验证的分界点。如果实现工作流已完成测试、Lint 检查和最终格式化，且候选内容没有变化，就不要重新运行这些检查。

如果合并 master 或准备 PR 时更改了源代码、测试、清单、生成的代码或配置，请按以下顺序验证新的候选内容：

1. 运行相关测试并修复代码，直到测试通过。
2. 运行适用的 Clippy 及其他 Lint、类型检查或构建检查，并修复发现的问题。只有在修复实质性改变行为时，才重新运行受影响的测试。
3. 在完成所有其他代码更改后，运行一次 ./script/format。

格式化后不要重新运行测试或 Lint；除非用户、任务或获批的规范明确要求，否则不要运行 ./script/presubmit。CI 负责处理目标本地覆盖范围之外的少见故障。仅涉及文档的更改无需运行 Rust 测试、Clippy 或格式化。

4. 关联 Linear 任务

条件允许时，PR 应关联 Linear 任务。使用 Linear MCP 工具（如果可用）查找对应的问题。

分支命名约定： 远程分支应以你的名字为前缀（例如，zheng/feature、alice/fix-bug）。

如何将 PR 关联到 Linear： 在 PR 标题中加入问题 ID（例如，[WARP-1234] Add new feature）。请在创建 PR 之前完成此操作，以便自动关联。

5. 创建 PR

创建 PR 时使用 .github/pull_request_template.md 中的 PR 模板。

适当时，按照 PR 模板底部的格式添加变更日志条目。示例：

• 功能："Global search in files across your current directories. Use CMD-F/CTRL-SHIFT-F to open."
• 改进："Added horizontal autoscrolling when jumping to line/column."
• Bug 修复："Fixed session viewer input being cleared when agent runs commands.

CLI 工作流：

• 检查当前分支是否已有 PR：

  gh pr view --json number,url
  

  PR 存在时退出代码为 0，不存在时为 1。

• 创建新 PR：

  # With title and body
  gh pr create --title "Title" --body "Description" --draft
  
  # Auto-fill from commits
  gh pr create --fill --draft
  
  # Use PR template file
  gh pr create --body-file .github/pull_request_template.md --title "Title" --draft
  

  关键标志：--draft / -d、--fill / -f、--body-file / -F、--web / -w

• 更新现有 PR：

  gh pr edit --title "New title" --body "New body"
  gh pr edit --add-reviewer username --add-label bug
  

• 将 PR 标记为准备好接受评审：

  gh pr ready
  

6. 添加共同作者署名

提交更改时，仅将署名作为提交信息末尾的 trailer 添加——不要放在 PR 描述中；如果提交中已有 Warp/Oz 共同作者 trailer，也不要再添加第二个：

Co-Authored-By: Warp Agent <[email protected]>

测试要求

Bug 修复需要回归测试

所有 Bug 修复都应配套回归测试。 这有助于防止已修复的问题再次出现。

测试应：

• 重现原始 Bug（修复前会失败）
• 在应用修复后通过
• 使用能清楚说明其防止什么 Bug 的名称

算法代码需要单元测试

具有非平凡逻辑的代码应通过单元测试验证功能：

需要单元测试的示例：

• 自定义数据结构（例如，SumTree）
• 对于给定查询应返回预期结果的搜索相关 API
• UI 框架中的核心布局代码
• 任何算法或计算逻辑

以下情况不需要：

• 足够简单的函数
• 简单的 getter/setter

编写单元测试时，请遵循仓库的本地测试惯例。

UI 组件需要布局验证测试

所有 UI 组件（View 的实现）都应有一个简单的单元测试，验证它们在布局时不会发生 panic。

这可以从较高层面覆盖渲染的“安全性”（但不覆盖“正确性”）：

#[test]
fn test_component_can_layout() {
    use warpui::App;
    use warp::test_util::{terminal::initialize_app_for_terminal_view, add_window_with_terminal};
    
    App::test((), |mut app| async move {
        initialize_app_for_terminal_view(&mut app);
        let term = add_window_with_terminal(&mut app, None);
        
        // Render the component - should not panic
        term.update(&mut app, |view, ctx| {
            // Create and layout your component
        });
    })
}

跳过集成测试覆盖前先询问

如果 PR 更改了用户可见的流程、修复了端到端回归问题，或者看起来适合增加集成测试覆盖，请在创建或更新 PR 前使用 ask_user_question 工具，询问用户是否希望在此次工作中添加集成测试。

优先提供直接的选项，例如：

• 是，创建 PR 前添加集成测试
• 否，继续，不添加集成测试

如果用户选择添加，请使用 warp-integration-test 技能。

P0 用例需要集成测试

所有“P0 用例”都需要集成测试，以覆盖相关行为或流程。

“P0 用例”的定义： 应用中任何一旦出问题就需要紧急发布的行为。

集成测试应：

• 覆盖完整的面向用户流程
• 验证端到端功能
• 放在 integration/ 目录中

有关实现细节、测试注册步骤和验证工作流，请使用 warp-integration-test 技能。

PR 描述指南

PR 描述正文请使用 write-pr-description 技能。该技能涵盖如何遵循仓库模板、正文的基本要求，以及何时添加阅读顺序和供审阅者关注的重点。

创建 PR 后

1. 监控 CI 检查 - 确保所有自动检查均通过
2. 回复审阅意见 - 及时处理反馈
3. 保持 PR 更新 - 出现冲突时合并 master
4. 验证变更的候选项 - 根据审阅反馈修改代码后，运行受影响的测试，然后运行 lint 检查，最后运行一次 ./script/format。对于 PR 元数据或未变更的候选项，不要重复验证。

最佳实践

• 让 PR 聚焦 - 尽可能让每个 PR 只包含一项逻辑变更
• 编写清晰的提交消息 - 说明做了什么以及原因，而不只是说明做了什么
• 先自行审阅 - 请求审阅前先检查自己的 diff
• 更新测试 - 确保测试覆盖能反映你的变更
• 记录破坏性变更 - 指出任何 API 变更或破坏性修改
• 使用功能标志 - 适当时使用功能标志控制风险较高的变更（参见 add-feature-flag 技能）