changelog

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Use this skill when creating, editing, or reviewing changelog entries under

src/content/changelog/

当你在

src/content/changelog/

目录下创建、编辑或审核变更日志条目时，请使用本技能。

Prerequisites

前置条件

You need three things before writing:

A product name (for example, Workers, KV, Hyperdrive, Containers, R2)
A description of the change being documented
Enough context to explain the "why" and use cases

If any are missing, ask for clarification. Do not proceed without all three.

开始撰写前，你需要准备以下三项内容：

产品名称（例如Workers、KV、Hyperdrive、Containers、R2）
待记录变更的描述
足够的上下文来解释变更的“原因”和使用场景

如果有任何一项缺失，请请求澄清。在集齐这三项前不要继续操作。

Determine the product folder

确定产品文件夹

Use the product name to find the correct folder under

src/content/changelog/{product}/

. Check existing folders for valid product names — do not guess.

根据产品名称在

src/content/changelog/{product}/

下找到对应的正确文件夹。请查看现有文件夹确认有效的产品名称——不要猜测。

Create the changelog file

创建变更日志文件

Path format:

src/content/changelog/{product}/{YYYY-MM-DD}-{useful-short-name}.mdx

Use today's date and a concise, hyphenated slug describing the change.

路径格式：

src/content/changelog/{product}/{YYYY-MM-DD}-{useful-short-name}.mdx

使用当前日期和一个简洁的、用连字符分隔的短名称来描述变更。

Frontmatter

前置元数据（Frontmatter）

yaml

---
title: <TITLE>
description: <ONE_SENTENCE_SUMMARY>
products:
  - <PRODUCT>
date: <YYYY-MM-DD>
---

yaml

---
title: <TITLE>
description: <ONE_SENTENCE_SUMMARY>
products:
  - <PRODUCT>
date: <YYYY-MM-DD>
---

Writing style

写作风格

Imperative mood, active voice
Opening sentence: what the feature/change is and what problem it solves
Expand on usage, use cases, and the "why" in subsequent paragraphs
Assume a technical developer/cloud audience
Keep sentences concise (8-12 words where possible)
Do not use contractions
Do not use LLM-like phrases ("It's important to note", "leverage", "seamless", etc.)
Replace
```
e.g.
```
with "for example" and
```
i.e.
```
with "that is"

采用祈使语气、主动语态
开篇句需明确说明功能/变更内容及其解决的问题
在后续段落中展开介绍用法、使用场景以及变更的初衷
目标读者为技术开发者/云服务从业者
句子力求简洁（尽可能控制在8-12词）
禁止使用英文缩略形式（如don’t、can’t）
避免使用类大语言模型的套话（如“It's important to note”“leverage”“seamless”等）
将
```
e.g.
```
替换为“for example”，将
```
i.e.
```
替换为“that is”

Code examples

代码示例

Include a code example when the changelog describes an API, SDK, or configuration change.

Include a code block demonstrating usage of the new feature
Use plain JavaScript/TypeScript code blocks (
```
js
```
or
```
ts
```
)
Use
```
jsonc
```
for wrangler.json config
Keep snippets short and focused on the new feature
Minimize boilerplate

Add imports if using components:

import { Render, TypeScriptExample, WranglerConfig } from "~/components";

当变更日志涉及API、SDK或配置变更时，需包含代码示例。

提供展示新功能用法的代码块
使用纯JavaScript/TypeScript代码块（标注
```
js
```
或
```
ts
```
）
对于wrangler.json配置，使用
```
jsonc
```
格式
代码片段应简短，聚焦于新功能
尽量减少样板代码

如果使用组件，需添加导入语句：

import { Render, TypeScriptExample, WranglerConfig } from "~/components";

Documentation links

文档链接

End the changelog with a link to relevant documentation:

Use relative paths (for example,
```
/workers/configuration/placement/
```
)
Link text must describe the destination — never "click here" or "read more"
Check for uncommitted/staged
```
.md
```
/
```
.mdx
```
files that might be the related documentation

在变更日志末尾添加相关文档的链接：

使用相对路径（例如
```
/workers/configuration/placement/
```
）
链接文本必须明确描述目标内容——绝不能使用“点击这里”或“了解更多”
检查是否有未提交/暂存的
```
.md
```
/
```
.mdx
```
文件可能是相关文档

Reference examples

参考示例

Review these existing changelogs for style and format guidance:

```
src/content/changelog/workers/
```
- Workers changelogs with code examples
```
src/content/changelog/kv/
```
- KV changelogs
```
src/content/changelog/hyperdrive/
```
- Hyperdrive changelogs
```
src/content/changelog/containers/
```
- Container changelogs

Read 2-3 entries from the target product's changelog folder before writing to match style and depth. If the target folder has fewer than 2 entries, read from the folders listed above as a reference.

请查看以下现有变更日志，获取样式和格式指导：

```
src/content/changelog/workers/
```
- 包含代码示例的Workers变更日志
```
src/content/changelog/kv/
```
- KV变更日志
```
src/content/changelog/hyperdrive/
```
- Hyperdrive变更日志
```
src/content/changelog/containers/
```
- Containers变更日志

在开始撰写前，阅读目标产品变更日志文件夹中的2-3条条目，以匹配其风格和深度。如果目标文件夹中的条目少于2条，请以上面列出的文件夹中的内容作为参考。

Editing existing entries

编辑现有条目

When updating an existing changelog entry, preserve the original structure and voice. Apply only the requested changes — do not rewrite surrounding content.

当更新现有变更日志条目时，请保留原始结构和语气。仅应用请求的变更——不要重写周围的内容。

Reviewing changelog entries

审核变更日志条目

When reviewing, validate against every section above: frontmatter fields, file path conventions, writing style, code example quality, and documentation links. Flag issues by severity:

Error: Missing required frontmatter fields, wrong product folder, broken links
Warning: Style violations, missing code examples for API changes, vague descriptions
Nit: Minor phrasing improvements

审核时，请对照上述所有部分进行验证：前置元数据字段、文件路径规范、写作风格、代码示例质量以及文档链接。按严重程度标记问题：

错误：缺失必填前置元数据字段、产品文件夹错误、链接失效
警告：违反写作风格、API变更缺失代码示例、描述模糊
细微问题：措辞的小改进

Output

输出

Create or update the changelog file and show the complete file path and content.

创建或更新变更日志文件，并展示完整的文件路径和内容。