create-pr

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

create-pr

Overview

概述

This guide covers best practices for creating pull requests in the warp repository, including merging master, running presubmit checks, linking Linear tasks, ensuring appropriate test coverage, and structuring your PR for effective review.

本指南介绍了在warp仓库中创建拉取请求的最佳实践，包括合并master分支、运行预提交检查、关联Linear任务、确保合适的测试覆盖率，以及构建便于审核的PR结构。

Related Skills

Pre-PR Checklist

PR创建前检查清单

1. Merge master into your feature branch

1. 将master分支合并到你的功能分支

Always merge master into your feature branch before starting the review process.

bash

git fetch origin
git merge origin/master

Resolve any merge conflicts locally before opening the PR.

在开始审核流程前，务必将master分支合并到你的功能分支中。

bash

git fetch origin
git merge origin/master

在开启PR前，先在本地解决所有合并冲突。

2. Run presubmit checks for code changes

2. 为代码变更运行预提交检查

If the PR includes code changes, run the relevant presubmit checks before opening or updating it:

bash

./script/presubmit

./script/presubmit

runs:

```
cargo fmt
```
- Code formatting
```
cargo clippy
```
- Linting with all warnings as errors
All tests (unit, doc, and integration) If the PR is documentation-only (for example, skills, markdown, or other non-code content), you do not need to run
```
cargo fmt
```
or
```
cargo clippy
```
just to open or update the PR.

If presubmit fails for a code-changing PR, use the

fix-errors

skill to resolve issues.

You must run
cargo fmt
and
cargo clippy
before:

Opening a new PR that includes code changes
Pushing new commits that include code changes to an existing PR branch
Any reviewed branch update that changes code

如果PR包含代码变更，在开启或更新PR前运行相关的预提交检查：

bash

./script/presubmit

./script/presubmit

会运行：

```
cargo fmt
```
- 代码格式化
```
cargo clippy
```
- 代码检查（所有警告视为错误）
所有测试（单元测试、文档测试和集成测试）如果PR仅涉及文档（例如技能文档、markdown或其他非代码内容），则无需为开启或更新PR而运行
```
cargo fmt
```
或
```
cargo clippy
```
。

如果代码变更类PR的预提交检查失败，请使用

fix-errors

技能解决问题。

在以下场景前必须运行
cargo fmt
和
cargo clippy
：

开启包含代码变更的新PR
向现有PR分支推送包含代码变更的新提交
任何涉及代码变更的已审核分支更新

3. Review your changes

3. 审核你的变更

Before creating a PR, review what changes you're about to submit:

bash

undefined

在创建PR前，审核你即将提交的变更：

bash

undefined

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


This helps you:
- Verify all intended changes are included
- Catch unintended changes before review
- Write an accurate PR description
- Ensure you're comparing against the correct base branch
- **Tests:** Include tests when required—bug fixes (regression test), algorithmic code (unit tests), UI components (layout test), P0 use cases (integration test). See Testing Requirements below.

git --no-pager diff <base-branch>...HEAD


这有助于你：
- 验证所有预期变更都已包含
- 在审核前发现意外变更
- 撰写准确的PR描述
- 确保对比的是正确的基准分支
- **测试：** 必要时添加测试——Bug修复（回归测试）、算法代码（单元测试）、UI组件（布局测试）、P0用例（集成测试）。详见下方的测试要求。

4. Link to Linear task

4. 关联Linear任务

When possible, PRs should be associated with a Linear task. Use the Linear MCP tool (if available) to find corresponding issues.

Branch naming convention: Remote branches should be prefixed with your name (e.g.,

zheng/feature

alice/fix-bug

How to link PRs to Linear: Include the issue ID in the PR title (e.g.,

[WARP-1234] Add new feature

). Do this before creating the PR for automatic linking.

尽可能让PR关联Linear任务。使用Linear MCP工具（若可用）查找对应的问题。

分支命名规范： 远程分支应以你的名字为前缀（例如：

zheng/feature

、

alice/fix-bug

）。

如何将PR与Linear关联： 在PR标题中包含问题ID（例如：

[WARP-1234] 添加新功能

）。请在创建PR前完成此操作以实现自动关联。

5. Open the PR

5. 开启PR

Use the PR template at

.github/pull_request_template.md

when opening PRs.

Add changelog entries when appropriate using the format at the bottom of the PR template. Some examples:

Feature: "Global search in files across your current directories. Use CMD-F/CTRL-SHIFT-F to open."
Improvement: "Added horizontal autoscrolling when jumping to line/column."
Bug fix: "Fixed session viewer input being cleared when agent runs commands.

CLI workflow:

Check if PR exists for current branch:
bash
```
gh pr view --json number,url
```
Exit code 0 if PR exists, 1 if not.

Create a new PR:

bash

# 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

Key flags:

--draft

-d

--fill

-f

--body-file

-F

--web

-w

Update an existing PR:

bash

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

Mark PR ready for review:
bash
```
gh pr ready
```

开启PR时使用

.github/pull_request_template.md

中的PR模板。

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

Feature: "全局搜索当前目录下的文件。使用CMD-F/CTRL-SHIFT-F打开。"
Improvement: "添加了跳转到指定行/列时的水平自动滚动功能。"
Bug fix: "修复了Agent运行命令时会话查看器输入被清空的问题。"

CLI工作流：

检查当前分支是否已存在PR：
bash
```
gh pr view --json number,url
```
若PR存在则退出码为0，不存在则为1。

创建新PR：

bash

# 指定标题和正文
gh pr create --title "Title" --body "Description" --draft

# 从提交记录自动填充内容
gh pr create --fill --draft

# 使用PR模板文件
gh pr create --body-file .github/pull_request_template.md --title "Title" --draft

关键参数：

--draft

-d

、

--fill

-f

、

--body-file

-F

、

--web

-w

更新现有PR：

bash

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

标记PR已准备好审核：
bash
```
gh pr ready
```

6. Include co-author attribution

6. 添加合著者署名

When committing changes or creating a PR, include attribution at the end of every commit message or PR description:

Co-Authored-By: Warp <agent@warp.dev>

在提交变更或创建PR时，在每个提交消息或PR描述的末尾添加署名：

Co-Authored-By: Warp <agent@warp.dev>

Testing Requirements

测试要求

Bug fixes require regression tests

Bug修复需包含回归测试

All bug fixes should be accompanied by a regression test. This helps prevent re-breaking something that was already broken once.

The test should:

Reproduce the original bug (would fail before the fix)
Pass after the fix is applied
Be clearly named to indicate what bug it's preventing

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

测试应：

复现原始Bug（修复前会失败）
修复后可通过
命名清晰，明确说明其预防的Bug

Algorithmic code requires unit tests

算法代码需包含单元测试

Code with non-trivial logic should have unit tests to validate functionality:

Examples of what needs unit tests:

Custom data structures (e.g.,
```
SumTree
```
)
Search-related APIs that should return expected results for a given query
Core layout code in the UI framework
Any algorithmic or computational logic

Not required for:

Sufficiently-simple functions
Trivial getters/setters

Follow the repository's local testing conventions for guidance on writing unit tests.

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

需要单元测试的示例：

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

无需单元测试的情况：

足够简单的函数
简单的getter/setter方法

遵循仓库的本地测试规范来编写单元测试。

UI components need layout validation tests

UI组件需要布局验证测试

All UI components (implementations of
View
) should have a simple unit test to validate that they can be laid out without a panic.

This provides high-level coverage over rendering "safety" (though not "correctness"):

rust

#[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
        });
    })
}

所有UI组件（
View
的实现）都应包含一个简单的单元测试，以验证它们可以正常布局而不会崩溃。

这提供了对渲染“安全性”的高层覆盖（而非“正确性”）：

rust

#[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);
        
        // 渲染组件——不应崩溃
        term.update(&mut app, |view, ctx| {
            // 创建并布局你的组件
        });
    })
}

Ask before skipping integration coverage

跳过集成测试前需询问

If the PR changes a user-visible flow, fixes an end-to-end regression, or otherwise looks like it would benefit from integration coverage, use the

ask_user_question

tool before creating or updating the PR to ask whether the user wants an integration test added as part of the work.

Prefer a direct choice such as:

Yes, add an integration test before creating the PR

No, continue without an integration test

If the user chooses to add one, use the

warp-integration-test

skill.

如果PR修改了用户可见流程、修复了端到端回归问题，或看起来能从集成测试中获益，在创建或更新PR前使用

ask_user_question

工具询问用户是否要在工作中添加集成测试。

提供明确的选项，例如：

Yes, add an integration test before creating the PR

（是，在创建PR前添加集成测试）

No, continue without an integration test

（否，不添加集成测试继续）

如果用户选择添加，请使用

warp-integration-test

技能。

P0 use cases require integration tests

P0用例需包含集成测试

All "P0 use cases" require an integration test that covers the behavior/flow in question.

A "P0 use case" is defined as: Any behavior of the application that, if broken, warrants an out-of-band release.

Integration tests should:

Exercise the full user-facing flow
Validate end-to-end functionality
Be placed in the
```
integration/
```
directory

Use the

warp-integration-test

skill for implementation details, test registration steps, and validation workflow.

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

“P0用例”定义为： 应用程序中任何若出现故障则需要紧急发布修复的行为。

集成测试应：

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

使用

warp-integration-test

技能获取实现细节、测试注册步骤和验证工作流。

PR Description Guidelines

PR描述指南

Your PR summary under the "Description" section should include:

What - What changes are being made
Why - Why these changes are necessary (link to Linear task if applicable)
How - Brief explanation of the approach taken

“描述”部分的PR摘要应包含：

内容 - 正在进行哪些变更
原因 - 这些变更为何必要（若适用请关联Linear任务）
方式 - 所采用方法的简要说明

After Opening the PR

开启PR后

Monitor CI checks - Ensure all automated checks pass
Respond to review comments - Address feedback promptly
Keep the PR up to date - Merge master if conflicts arise
Re-run relevant validation - After making changes based on review feedback. For code changes, re-run
```
cargo fmt
```
/
```
cargo clippy
```
(and other relevant checks); for documentation-only changes, this is not required.

监控CI检查 - 确保所有自动化检查通过
响应审核意见 - 及时处理反馈
保持PR更新 - 若出现冲突则合并master分支
重新运行相关验证 - 根据审核反馈做出变更后，重新运行相关验证。对于代码变更，重新运行
```
cargo fmt
```
/
```
cargo clippy
```
（及其他相关检查）；对于仅文档变更，无需此操作。

Best Practices

最佳实践

Keep PRs focused - One logical change per PR when possible
Write clear commit messages - Explain what and why, not just what
Self-review first - Review your own diff before requesting review
Update tests - Ensure test coverage reflects your changes
Document breaking changes - Call out any API changes or breaking modifications
Use feature flags - Gate risky changes behind feature flags when appropriate (see the
```
add-feature-flag
```
skill)

保持PR聚焦 - 尽可能每个PR只包含一个逻辑变更
撰写清晰的提交消息 - 说明变更内容和原因，而非仅说明内容
先自我审核 - 在请求他人审核前先自行查看差异内容
更新测试 - 确保测试覆盖率反映你的变更
记录破坏性变更 - 明确指出任何API变更或破坏性修改
使用功能标记 - 适当时用功能标记管控高风险变更（详见
```
add-feature-flag
```
技能）

create-pr

Original

Translation

create-pr

create-pr

Overview

概述

Related Skills

相关技能

Pre-PR Checklist

PR创建前检查清单

1. Merge master into your feature branch

1. 将master分支合并到你的功能分支

2. Run presubmit checks for code changes

2. 为代码变更运行预提交检查

3. Review your changes

3. 审核你的变更

View commits in your branch (comparing against base branch)

查看分支中的提交（与基准分支对比）

View file statistics for changes

查看变更的文件统计信息

View full diff

查看完整的差异内容

4. Link to Linear task

4. 关联Linear任务

5. Open the PR

5. 开启PR

6. Include co-author attribution

6. 添加合著者署名

Testing Requirements

测试要求

Bug fixes require regression tests

Bug修复需包含回归测试

Algorithmic code requires unit tests

算法代码需包含单元测试

UI components need layout validation tests

UI组件需要布局验证测试

Ask before skipping integration coverage

跳过集成测试前需询问

P0 use cases require integration tests

P0用例需包含集成测试

PR Description Guidelines

PR描述指南

After Opening the PR

开启PR后

Best Practices

最佳实践