Back to Details

finish-line

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Finish Line

终点线

Overview

概述

Finish blocked community PRs in 
remix-run/react-router
while respecting contributor ownership and the repo's PR packaging conventions.
Treat the PR number or URL in 
$ARGUMENTS
as the target PR. If no target is provided, ask for it before doing anything.
在尊重贡献者所有权和仓库 PR 打包规范的前提下，完成 
remix-run/react-router
仓库中受阻的社区 PR 收尾工作。
将 
$ARGUMENTS
中的 PR 编号或 URL 作为目标 PR。如果未提供目标，请先询问用户再进行任何操作。

Triage

初步排查

  1. Inspect local state with 
    git status --short --branch
    . If unrelated dirty files exist, do not overwrite or stage them.
  2. Fetch current main before making branch decisions:
sh
git fetch origin main
  1. Gather PR context:
sh
gh pr view <pr> --repo remix-run/react-router --json number,title,body,state,isDraft,author,baseRefName,headRefName,headRepository,headRepositoryOwner,maintainerCanModify,mergeStateStatus,reviewDecision,labels,files,commits,statusCheckRollup,url
gh pr checks <pr> --repo remix-run/react-router
gh pr diff <pr> --repo remix-run/react-router --stat
gh pr view <pr> --repo remix-run/react-router --comments
  1. Identify merge blockers. In particular:
  • If the PR only needs repo-maintainer additions such as tests, a change file, or docs, use the contributor-branch workflow.
  • If the contributor branch cannot be modified, summarize the evidence and ask the user whether to wait for the contributor or recreate the work on a maintainer branch.
  • If the blocker is unclear, summarize the evidence and ask the user which path to take.
  1. Evaluate test coverage before deciding the finish-line changes:
    • Inspect the PR diff, changed files, existing nearby tests, review comments, and failed checks for test expectations.
    • If the PR changes runtime behavior, build/plugin behavior, routing semantics, generated types, RSC behavior, docs rendering, or any bug/feature surface that can regress, add or preserve a focused test unless equivalent coverage already exists.
    • If tests are already included, verify they exercise the changed behavior and cover the affected React Router mode(s): Declarative, Data, Framework, RSC Data, and/or RSC Framework.
    • If tests are not needed because the change is documentation-only, packaging-only, a change file, or otherwise not executable behavior, note that rationale in the final report.
    • If a useful test is required but too large or risky for the finish-line scope, stop and ask the user before broadening the PR.
  1. 使用 
    git status --short --branch
    检查本地状态。如果存在不相关的未提交文件，请勿覆盖或暂存它们。
  2. 在做出分支决策前，先获取当前的 main 分支：
sh
git fetch origin main
  1. 收集 PR 上下文信息：
sh
gh pr view <pr> --repo remix-run/react-router --json number,title,body,state,isDraft,author,baseRefName,headRefName,headRepository,headRepositoryOwner,maintainerCanModify,mergeStateStatus,reviewDecision,labels,files,commits,statusCheckRollup,url
gh pr checks <pr> --repo remix-run/react-router
gh pr diff <pr> --repo remix-run/react-router --stat
gh pr view <pr> --repo remix-run/react-router --comments
  1. 识别合并阻塞项，重点关注：
  • 如果 PR 仅需要仓库维护者补充内容（如测试、change file 或文档），则使用贡献者分支工作流。
  • 如果贡献者分支无法修改，请总结相关证据，询问用户是等待贡献者更新，还是在维护者分支上重现该工作。
  • 如果阻塞项不明确，请总结证据，询问用户应采取哪种方案。
  1. 在决定终点线修改内容之前，评估测试覆盖率：
    • 检查 PR 差异、变更文件、附近现有的测试、评审评论以及未通过的检查，以明确测试预期。
    • 如果 PR 更改了运行时行为、构建/插件行为、路由语义、生成的类型、RSC 行为、文档渲染，或任何可能出现回归的 bug/功能面，请添加或保留针对性测试，除非已存在等效的覆盖率。
    • 如果 PR 已包含测试，请验证它们确实测试了变更的行为，并覆盖了受影响的 React Router 模式：Declarative、Data、Framework、RSC Data 和/或 RSC Framework。
    • 如果变更仅涉及文档、打包配置、change file 或其他非可执行行为，因此不需要测试，请在最终报告中说明该理由。
    • 如果需要添加有价值的测试，但测试范围过大或风险超出终点线工作的范畴，请停止操作，在扩大 PR 范围前先询问用户。

Contributor-Branch Workflow

贡献者分支工作流

Use this path when the missing work is a small maintainer follow-up, such as tests, a change file, or docs, and the contributor branch can be modified.
  1. Check out the PR branch:
sh
gh pr checkout <pr-number> --repo remix-run/react-router
  1. Confirm the branch and local state:
sh
git status --short --branch
git branch --show-current
  1. Make only the missing finish-line changes, including focused tests when the coverage evaluation requires them. Do not refactor the contributor's work unless it is necessary to unblock mergeability and the user agrees.
  2. Validate the exact content with the user before pushing:
    • For a change file, show the package path, file name, change type, and full markdown contents.
    • For docs, show the affected files and the relevant prose/API snippets.
    • For tests, show the test file path, the behavior covered, and the mode(s) covered.
    • Ask explicitly for approval to commit and push back to the PR branch.
  3. After approval, run focused validation when appropriate, commit the maintainer follow-up, and push to the PR branch. If 
    git push
    fails because the contributor branch cannot be modified, stop and report the failure instead of opening a replacement PR unless the user approves that pivot.
当缺失的工作是小型的维护者跟进内容（如测试、change file 或文档），且贡献者分支可修改时，使用此流程。
  1. 检出 PR 分支：
sh
gh pr checkout <pr-number> --repo remix-run/react-router
  1. 确认分支和本地状态：
sh
git status --short --branch
git branch --show-current
  1. 仅添加缺失的终点线修改内容，包括覆盖率评估要求的针对性测试。请勿重构贡献者的代码，除非这是解除合并阻塞的必要条件，且用户已同意。
  2. 推送前与用户确认具体的修改内容：
    • 对于 change file，展示包路径、文件名、变更类型和完整的 markdown 内容。
    • 对于文档，展示受影响的文件和相关的说明/API 片段。
    • 对于测试，展示测试文件路径、覆盖的行为以及覆盖的模式。
    • 明确请求用户批准提交并推送到 PR 分支。
  3. 获得批准后，在适当的时候运行针对性验证，提交维护者的跟进内容，并推送到 PR 分支。如果由于贡献者分支无法修改导致 
    git push
    失败，请停止操作并报告失败原因，不要直接打开替代 PR，除非用户批准该转向操作。

Change Files

Change Files

Create change files under the affected package:
text
packages/<package>/.changes/<type>.<unique-meaningful-name>.md
Use 
patch
, 
minor
, 
major
, or 
unstable
for 
<type>
. For bug fixes and narrow behavior fixes, default to 
patch
. Keep the content concise:
markdown
Brief description of the user-facing change
If the PR spans multiple packages, prefer the package with the direct user-facing API or runtime behavior. Ask the user when the package or change type is not obvious.
在受影响的包下创建 change file：
text
packages/<package>/.changes/<type>.<unique-meaningful-name>.md
<type>
可使用 
patch
、
minor
、
major
或 
unstable
。对于 bug 修复和小范围行为修复，默认使用 
patch
。内容保持简洁：
markdown
Brief description of the user-facing change
如果 PR 涉及多个包，优先选择有直接面向用户的 API 或运行时行为的包。如果包或变更类型不明确，请询问用户。

Documentation

文档

Do not add documentation by default for ordinary bug fixes. Add docs when the PR changes a documented API, introduces new behavior users need to discover, changes examples, or the user/reviewer explicitly requested docs.
Follow repo docs rules:
  • Edit source docs or JSDoc, not generated 
    docs/api/
    output.
  • Include mode context when adding docs for React Router behavior: Declarative, Data, Framework, RSC Data, or RSC Framework.
  • For API docs generated from JSDoc, edit 
    packages/react-router/lib/
    comments and note that 
    pnpm run docs
    may be required.
对于普通的 bug 修复，默认不添加文档。当 PR 更改了已记录的 API、引入了用户需要了解的新行为、更改了示例，或者用户/评审者明确要求添加文档时，再补充文档。
遵循仓库文档规范：
  • 编辑源文档或 JSDoc，不要编辑生成的 
    docs/api/
    输出内容。
  • 为 React Router 行为添加文档时，需包含模式上下文：Declarative、Data、Framework、RSC Data 或 RSC Framework。
  • 对于从 JSDoc 生成的 API 文档，请编辑 
    packages/react-router/lib/
    中的注释，并说明可能需要运行 
    pnpm run docs
    。

Final Report

最终报告

Report the path taken and the current PR state:
  • Original PR number and blocker.
  • Whether changes were pushed to the contributor branch or a replacement PR was opened.
  • Branch, commit hash, and PR URL when applicable.
  • Any old-PR comment/close action taken.
  • Validation performed or skipped.
  • Test coverage decision: added, already present, or intentionally omitted with rationale.
报告所采取的流程和当前 PR 状态：
  • 原始 PR 编号和阻塞项。
  • 修改内容是推送到了贡献者分支，还是打开了替代 PR。
  • 适用时，提供分支、提交哈希和 PR URL。
  • 对旧 PR 采取的任何评论/关闭操作。
  • 已执行或跳过的验证。
  • 测试覆盖率决策：已添加、已存在，或有意省略并说明理由。