astro-pr-writer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Astro PR Writer

Astro PR 撰写指南

Write Astro pull request descriptions that help reviewers quickly understand intent, behavior changes, and validation.

Use this skill whenever the user asks for any PR-writing task, including:

create/open a pull request
create/open a draft pull request
update a PR title
update a PR body/description
write PR notes/summary

撰写便于评审者快速理解意图、行为变更和验证内容的Astro拉取请求描述。

当用户提出任何PR撰写需求时，均可使用此技能，包括：

创建/打开拉取请求
创建/打开草拟拉取请求
更新PR标题
更新PR正文/描述
撰写PR说明/摘要

Core Principle

核心原则

Describe the change, how it works, and why it matters.

```
Changes
```
explains what the fix/feature does.
```
Testing
```
lists what test code was added or changed.
```
Docs
```
explains whether user-facing docs changes are needed.

Do not use PR sections as a task log.

描述变更内容、实现方式和重要性。

```
Changes
```
说明修复/功能的具体作用。
```
Testing
```
列出新增或修改的测试代码。
```
Docs
```
说明是否需要面向用户的文档变更。

请勿将PR章节用作任务日志。

PR Title Rules

PR标题规则

Use a human, reviewer-friendly title.

Describe the outcome in plain language.
Keep it concise and specific.
Prefer phrasing a person would naturally write in a review queue.

Do not use:

conventional commit prefixes in PR titles (
```
fix:
```
,
```
feat:
```
,
```
docs:
```
, etc.)
scoped commit-style titles (
```
fix(cloudflare): ...
```
)

使用便于评审者理解的人性化标题。

用平实语言描述最终结果。
保持简洁且具体。
优先采用评审队列中人们自然会使用的表述方式。

请勿使用：

PR标题中的常规提交前缀（
```
fix:
```
、
```
feat:
```
、
```
docs:
```
等）
带作用域的提交式标题（
```
fix(cloudflare): ...
```
）

Body Rules

PR正文规则

Use this structure:

undefined

使用以下结构：

undefined

Changes

变更内容

<Behavior change and why it matters>
<Implementation detail and impact>

<行为变更及其重要性>
<实现细节与影响>

Testing

测试说明

<New or changed test and what it covers>
<Why an existing assertion changed>

<新增或修改的测试及其覆盖范围>
<现有断言变更的原因>

Docs

文档说明

<No docs update needed, because ...>

undefined

<无需更新文档，原因：...>

undefined

Changes

变更内容

Focus on behavior, implementation approach, and impact.

Include:

what now works that did not work before
how the fix/feature works (reviewer-useful level)
user-facing reliability/compatibility/perf behavior changes

Do not include:

"added test" or "updated fixture" (belongs in
```
Testing
```
)
"added changeset"
internal process notes with no behavior impact

聚焦于行为、实现方式和影响。

需包含：

之前无法实现现在已正常工作的功能
修复/功能的实现方式（达到便于评审者理解的程度）
面向用户的可靠性/兼容性/性能行为变更

请勿包含：

"新增测试"或"更新测试用例"（属于
```
Testing
```
章节）
"添加changeset"
无行为影响的内部流程说明

Testing

测试说明

List what test code was added or changed, and why. Reviewers read this section to understand test coverage changes — not to hear that you ran a test suite.

Include:

new test files or test cases added, with a short description of what they cover
existing tests that were updated, and why the assertion changed

Do not include:

that tests pass (CI shows this; it's noise)
which commands you ran
how many tests passed

列出新增或修改的测试代码及其原因。评审者阅读此章节是为了了解测试覆盖范围的变化——而非得知你运行了测试套件。

需包含：

新增的测试文件或测试用例，简要描述其覆盖范围
已更新的现有测试，以及断言变更的原因

请勿包含：

测试已通过（CI会展示此信息，属于冗余内容）
你执行过哪些命令
通过的测试数量

Docs

文档说明

Explain docs impact clearly.

If docs are not needed, say why in one sentence.
If docs are needed, link the docs PR.

清晰说明对文档的影响。

若无需更新文档，用一句话说明原因。
若需要更新文档，关联对应的文档PR。

Brevity Guidance

简洁性指导

Default to short. 1-2 bullets per section is normal — add more only when the change is genuinely complex. A reviewer scanning a PR queue should be able to read the whole body in under 30 seconds for a typical patch.

Too verbose:

Moves
.optional().prefault({})
outside
z.preprocess()
for the
server
config property in both
base.ts
and
relative.ts
, matching the
integrations
fix from #16531. Zod 4.4.0 rejects missing properties wrapped in
z.preprocess()
before the preprocessor or inner defaults can execute — moving
.optional().prefault({})
outside the preprocess call resolves this. Fixes the
server
property issue reported there by @rururux.
Adds
invalid_key
,
invalid_element
, and discriminated union
options
handlers to both Astro and DB error maps for Zod 4.4.0 compatibility. Zod 4.4.0 surfaces record key refinement failures (e.g. env schema variable names) as structured
invalid_key
issues with nested errors instead of a flat message. The handlers extract the actual refinement message for clear user-facing errors.
All changes are backward-compatible with Zod 4.3.x. New error map branches only activate on issue codes that 4.4.0 starts emitting.

Better:

Moves
.optional().prefault({})
outside
z.preprocess()
for the
server
config, matching the
integrations
fix from #16531. Fixes the issue reported there by @rururux.
Adds
invalid_key
,
invalid_element
, and discriminated union
options
handlers to both error maps for Zod 4.4.0 compat.
Backward-compatible with Zod 4.3.x.

默认保持简洁。每个章节1-2个项目符号是常规情况——仅当变更确实复杂时再添加更多内容。评审者在浏览PR队列时，应能在30秒内读完常规补丁的完整正文。

过于冗长的示例：

将
.optional().prefault({})
从
z.preprocess()
外移至
server
配置属性（在
base.ts
和
relative.ts
中均有修改），与#16531中
integrations
的修复方式一致。Zod 4.4.0会拒绝
z.preprocess()
包裹的缺失属性，导致预处理器或内部默认值无法执行——将
.optional().prefault({})
移至预处理调用外可解决此问题。修复了@rururux在该issue中报告的
server
属性问题。
为Astro和DB错误映射添加
invalid_key
、
invalid_element
和区分联合
options
处理程序，以兼容Zod 4.4.0。Zod 4.4.0会将记录键细化失败（例如环境模式变量名）作为结构化的
invalid_key
问题呈现，并附带嵌套错误，而非扁平化消息。这些处理程序会提取实际的细化消息，以便为用户提供清晰的错误提示。
所有变更均向后兼容Zod 4.3.x。新的错误映射分支仅在4.4.0开始生成的问题代码时激活。

优化后的示例：

将
.optional().prefault({})
从
z.preprocess()
外移至
server
配置，与#16531中
integrations
的修复方式一致。修复了@rururux在该issue中报告的问题。
为两个错误映射添加
invalid_key
、
invalid_element
和区分联合
options
处理程序，以兼容Zod 4.4.0。
向后兼容Zod 4.3.x。

Changesets

Changeset

Every PR that modifies a package requires a changeset. Only

examples/*

changes are exempt.

Load the

changeset

skill to create the changeset file and write the message. It covers file creation, format, bump types, and message conventions.

When writing the PR body:

Always check that a changeset exists before posting the PR
Do not mention "added changeset" in the
```
Changes
```
section — it is process noise, not a behavior change

所有修改包的PR都需要一个changeset。仅

examples/*

目录下的变更可豁免。

加载

changeset

技能以创建changeset文件并撰写消息。该技能涵盖文件创建、格式、版本 bump类型和消息约定。

撰写PR正文时：

在发布PR前务必确认changeset已存在
请勿在
```
Changes
```
章节中提及“添加changeset”——这属于流程冗余内容，而非行为变更

Self-Check Before Posting

发布前自我检查

Title is reviewer-friendly (not commit-style)
```
Changes
```
bullets describe behavior/implementation/impact
```
Testing
```
lists test code added/changed, not test run results
```
Docs
```
decision is explicit
Changeset file exists in
```
.changeset/
```
for any package-modifying PR

标题便于评审者理解（非提交式标题）
```
Changes
```
项目符号描述了行为/实现/影响
```
Testing
```
列出了新增/修改的测试代码，而非测试运行结果
```
Docs
```
的决策明确
任何修改包的PR都在
```
.changeset/
```
目录下存在changeset文件