Back to Details

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
:
  1. Check implementation status to verify:
    • What's actually completed vs planned
    • Current limitations and known gaps
    • Technical accuracy of claims
  2. 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"
  3. 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
进行验证：
  1. 核查实现状态以确认：
    • 已完成内容与计划内容的差异
    • 当前限制和已知不足
    • 表述的技术准确性
  2. 切勿夸大其词：
    • 使用具体名称：例如使用“GitHub File Sync (File Contents)”而非“GitHub Integration”
    • 披露限制：例如“当前支持X；Y功能将在vZ版本中推出”
    • 如实说明条件：例如“当有3位以上客户提出需求时”
  3. 验证所有表述：
    • 如果引用数字，请确认其在实现文档中存在
    • 如果提及某项功能，请确认其已在生产环境中上线
    • 如有疑问，请寻求澄清

Writing Guidelines

撰写准则

  1. Concise & scannable: 1-3 sentences per feature (Cursor-style brevity)
  2. Lead with benefit: Start with what users can do, then how
  3. Be transparent: Mention beta status, rollout timelines, limitations
  4. User-focused but technical: Balance benefits with specifics developers need
  5. Active voice: "You can now..." not "Users are able to..."
  6. No emoji: Professional tone
  7. Specific examples: Include config snippets, API calls
  8. SEO-conscious: Use target keywords naturally
  9. AEO-conscious: Write 
    tldr
    for AI citation engines, 
    excerpt
    for listings
  10. FAQ quality: Questions must match real search queries, answers must be complete
  1. 简洁易读：每个功能描述控制在1-3句话（保持类似Cursor的简洁风格）
  2. 以用户收益为先导：先说明用户能做什么，再解释实现方式
  3. 保持透明：提及Beta状态、推出时间表和限制条件
  4. 兼顾用户视角与技术细节：在用户收益和开发者所需的技术细节之间取得平衡
  5. 使用主动语态：例如使用“你现在可以……”而非“用户能够……”
  6. 不使用表情符号：保持专业语气
  7. 提供具体示例：包含配置代码片段、API调用示例
  8. 注重SEO优化：自然融入目标关键词
  9. 适配AEO要求：为AI引用引擎撰写
    tldr
    内容，为列表页面撰写
    excerpt
    内容
  10. FAQ质量要求：问题需匹配真实搜索查询，答案需完整

Workflow

工作流程

  1. Gather input: PR numbers, URLs, or manual change list
  2. Read implementation status for fact-checking
  3. Draft following templates
  4. Cross-check claims against implementation reality
  5. Add SEO elements per seo-requirements
  6. Review with checklist
  1. 收集输入信息：PR编号、URL或手动整理的变更列表
  2. 查阅实现状态文档进行事实核查
  3. 按照模板撰写草稿
  4. 对照实际实现情况交叉验证所有表述
  5. 根据SEO要求添加SEO元素
  6. 使用检查清单进行审核

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要求
  • 示例
  • 发布前检查清单