changelog-writer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Changelog Writer

更新日志撰写指南

Create clear, accurate changelog entries that help developers understand what's new in Lightfast releases.

创建清晰、准确的更新日志条目，帮助开发者了解Lightfast版本中的新内容。

Critical: Fact-Check First

重要提示：先进行事实核查

Before writing anything, verify against

docs/architecture/implementation-status/README.md

Check implementation status to verify:
- What's actually completed vs planned
- Current limitations and known gaps
- Technical accuracy of claims
Never oversell:
- Use specific names: "GitHub File Sync (File Contents)" not "GitHub Integration"
- Disclose limitations: "Currently supports X; Y coming in vZ"
- Be honest about conditionals: "when 3+ customers request"
Verify every claim:
- If you cite a number, confirm it's in implementation docs
- If you mention a feature, confirm it exists in production
- When uncertain, ask for clarification

在撰写任何内容之前，请对照

docs/architecture/implementation-status/README.md

进行验证：

核查实现状态以确认：
- 已完成内容与计划内容的差异
- 当前限制和已知不足
- 表述的技术准确性
切勿夸大其词：
- 使用具体名称：例如使用“GitHub File Sync (File Contents)”而非“GitHub Integration”
- 披露限制：例如“当前支持X；Y功能将在vZ版本中推出”
- 如实说明条件：例如“当有3位以上客户提出需求时”
验证所有表述：
- 如果引用数字，请确认其在实现文档中存在
- 如果提及某项功能，请确认其已在生产环境中上线
- 如有疑问，请寻求澄清

Writing Guidelines

撰写准则

Concise & scannable: 1-3 sentences per feature (Cursor-style brevity)
Lead with benefit: Start with what users can do, then how
Be transparent: Mention beta status, rollout timelines, limitations
User-focused but technical: Balance benefits with specifics developers need
Active voice: "You can now..." not "Users are able to..."
No emoji: Professional tone
Specific examples: Include config snippets, API calls
SEO-conscious: Use target keywords naturally
AEO-conscious: Write
```
tldr
```
for AI citation engines,
```
excerpt
```
for listings
FAQ quality: Questions must match real search queries, answers must be complete

简洁易读：每个功能描述控制在1-3句话（保持类似Cursor的简洁风格）
以用户收益为先导：先说明用户能做什么，再解释实现方式
保持透明：提及Beta状态、推出时间表和限制条件
兼顾用户视角与技术细节：在用户收益和开发者所需的技术细节之间取得平衡
使用主动语态：例如使用“你现在可以……”而非“用户能够……”
不使用表情符号：保持专业语气
提供具体示例：包含配置代码片段、API调用示例
注重SEO优化：自然融入目标关键词
适配AEO要求：为AI引用引擎撰写
```
tldr
```
内容，为列表页面撰写
```
excerpt
```
内容
FAQ质量要求：问题需匹配真实搜索查询，答案需完整

Workflow

工作流程

Gather input: PR numbers, URLs, or manual change list
Read implementation status for fact-checking
Draft following templates
Cross-check claims against implementation reality
Add SEO elements per seo-requirements
Review with checklist

收集输入信息：PR编号、URL或手动整理的变更列表
查阅实现状态文档进行事实核查
按照模板撰写草稿
对照实际实现情况交叉验证所有表述
根据SEO要求添加SEO元素
使用检查清单进行审核

Quick Reference

快速参考

Do

正确做法

"GitHub File Sync (File Contents)" with limitations disclosed
"When 3+ customers request: Linear integration"
Include code examples for every major feature
Link to 3-5 related docs

使用“GitHub File Sync (File Contents)”并披露限制条件
例如“当有3位以上客户提出需求时：Linear集成”
为每个主要功能提供代码示例
链接到3-5个相关文档

Don't

错误做法

"GitHub Integration" (vague - what does it cover?)
"Coming soon: Linear, Notion, Slack!" (when at 0%)
Long paragraphs (keep to 1-3 sentences per feature)
Claims without verification

使用“GitHub Integration”（表述模糊：未说明涵盖内容）
使用“即将推出：Linear、Notion、Slack！”（当完成度为0%时）
冗长段落（每个功能描述控制在1-3句话）
未经验证的表述

Output

输出要求

Save drafts to:

thoughts/changelog/{title-slug}-{YYYYMMDD-HHMMSS}.md

草稿保存路径：

thoughts/changelog/{title-slug}-{YYYYMMDD-HHMMSS}.md

Required Frontmatter Fields

必需的前置字段

Every draft MUST include:

```
title
```
,
```
slug
```
,
```
publishedAt
```
(core)
```
excerpt
```
,
```
tldr
```
(AEO)
```
seo.metaDescription
```
,
```
seo.focusKeyword
```
(SEO)
```
_internal.status
```
,
```
_internal.source_prs
```
(traceability)

每个草稿必须包含以下字段：

```
title
```
,
```
slug
```
,
```
publishedAt
```
（核心字段）
```
excerpt
```
,
```
tldr
```
（适配AEO）
```
seo.metaDescription
```
,
```
seo.focusKeyword
```
（SEO相关）
```
_internal.status
```
,
```
_internal.source_prs
```
（可追溯性）

Slug Format

Slug格式

Always use:

0-<version>-lightfast-<feature-slug>

Examples:

0-1-lightfast-github-file-sync-semantic-search

0-2-lightfast-pr-metadata-linear-integration

Recommended:

```
seo.secondaryKeyword
```
,
```
seo.faq[]
```
(enhanced SEO)

The frontmatter structure maps directly to

ChangelogEntryInput

type. Use

/publish_changelog

to publish drafts to BaseHub.

See

resources/templates.md

for complete frontmatter template.

统一使用：

0-<version>-lightfast-<feature-slug>

示例：

0-1-lightfast-github-file-sync-semantic-search

0-2-lightfast-pr-metadata-linear-integration

推荐添加：

```
seo.secondaryKeyword
```
,
```
seo.faq[]
```
（增强SEO效果）

前置字段结构直接对应

ChangelogEntryInput

类型。使用

/publish_changelog

将草稿发布到BaseHub。

完整前置字段模板请参阅

resources/templates.md

。

Resources

参考资源

Document Templates
SEO Requirements
Examples
Pre-Publish Checklist

文档模板
SEO要求
示例
发布前检查清单