Back to Details

release-announcement

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

ax:release-announcement

ax:release-announcement

Write release announcements that are grounded in the actual release range and the agent sessions that produced it. This skill owns the curated layer under 
docs/releases/
; Release Please still owns 
CHANGELOG.md
.
Assumes 
ax
is on PATH and the local ax database is reachable. If 
ax
fails with a DB connection error, tell the user to start the repo DB and continue from git evidence only if they ask.
撰写基于实际版本范围及生成该版本的agent会话的发布公告。此技能负责
docs/releases/
下的精选内容层；
CHANGELOG.md
仍由Release Please负责。
假设
ax
已在PATH中，且本地ax数据库可访问。如果
ax
因数据库连接错误失败，请告知用户启动仓库数据库，若用户要求，仅基于git证据继续操作。

When to fire

触发场景

Use this skill for:
  • "write release notes" / "draft release announcement"
  • "prepare changelog" / "update the website changelog"
  • "release page" / "version page" / "SEO release page"
  • "what changed in vX.Y.Z"
  • "generate announcement for vX.Y.Z"
  • "explain how we got to this release"
Do not use this for a single commit message, generic README edits, or a non-release feature doc.
在以下场景使用此技能：
  • "write release notes" / "draft release announcement"（撰写版本说明/草拟发布公告）
  • "prepare changelog" / "update the website changelog"（准备变更日志/更新网站变更日志）
  • "release page" / "version page" / "SEO release page"（发布页面/版本页面/SEO优化的发布页面）
  • "what changed in vX.Y.Z"（vX.Y.Z版本有哪些变更）
  • "generate announcement for vX.Y.Z"（为vX.Y.Z版本生成发布公告）
  • "explain how we got to this release"（解释我们如何达成这个版本）
请勿将其用于单个提交消息、通用README编辑或非发布相关的功能文档。

Workflow

工作流程

1. Resolve the version and range

1. 确定版本及范围

If the version is known:
bash
bun run release:announcement -- X.Y.Z
This drafts 
docs/releases/vX.Y.Z.md
and, when the Release Please compare heading is present, embeds:
  • previous release tag (
    BASE_REF
    )
  • release tag or 
    HEAD
    (
    HEAD_REF
    )
  • git diff --name-status "$BASE_REF..$HEAD_REF"
  • git log --reverse --format='%h %cs %s' "$BASE_REF..$HEAD_REF"
If you need to inspect manually:
bash
BASE_REF=<previous-release-tag>
HEAD_REF=<release-head-or-tag>
git diff --name-status "$BASE_REF..$HEAD_REF"
git log --reverse --format='%h %cs %s' "$BASE_REF..$HEAD_REF"
若版本已知：
bash
bun run release:announcement -- X.Y.Z
此命令会草拟
docs/releases/vX.Y.Z.md
，当存在Release Please的对比标题时，会嵌入以下内容：
  • 上一版本标签（
    BASE_REF
    ）
  • 版本标签或
    HEAD
    （
    HEAD_REF
    ）
  • git diff --name-status "$BASE_REF..$HEAD_REF"
  • git log --reverse --format='%h %cs %s' "$BASE_REF..$HEAD_REF"
若需手动检查：
bash
BASE_REF=<previous-release-tag>
HEAD_REF=<release-head-or-tag>
git diff --name-status "$BASE_REF..$HEAD_REF"
git log --reverse --format='%h %cs %s' "$BASE_REF..$HEAD_REF"

2. Map commits and files to agent sessions

2. 将提交记录和文件映射到agent会话

Use the file list to identify touched subsystems. Use the commit list to pick important SHAs. Then query ax:
bash
ax ingest here --since=30d
ax sessions here --days=30
ax sessions near <important-sha>
ax recall "<subsystem or decision>" --sources=turn,commit --scope=here
For large releases, inspect at least:
  • one SHA per major topic
  • one SHA near each major schema/API/CLI change
  • any SHA tied to a surprising bug fix or reversal
  • session windows around the merge/release PR if available
使用文件列表确定受影响的子系统。使用提交列表挑选重要的SHA值。然后查询ax：
bash
ax ingest here --since=30d
ax sessions here --days=30
ax sessions near <important-sha>
ax recall "<subsystem or decision>" --sources=turn,commit --scope=here
对于大型版本，至少检查：
  • 每个主题对应一个SHA值
  • 每个主要Schema/API/CLI变更附近的一个SHA值
  • 任何与意外修复或回退相关的SHA值
  • 若有可用的合并/发布PR，检查其周围的会话窗口

3. Write the announcement

3. 撰写公告

Replace the generated draft with a topical narrative. Keep it concise, but make it useful:
  • How we got here - the problem, decision tree, tradeoffs, and why the final shape won. Cite session/commit evidence in prose.
  • What changed - grouped by topic, not one flat commit list.
  • Example - a CLI command, config snippet, output sample, schema fragment, or before/after workflow when the release changes behavior.
  • Visual evidence - screenshot, diagram, or output capture when a UI, CLI, dashboard, TUI, or workflow is easier to understand visually.
  • Why it matters - the practical day-to-day impact.
Do not invent motivation. If ax session evidence is missing, say what the commits and changed files prove and keep the story narrower.
将生成的草稿替换为主题式叙述。保持简洁，但确保实用：
  • 版本由来 - 问题、决策树、权衡因素，以及最终方案胜出的原因。在正文中引用会话/提交证据。
  • 变更内容 - 按主题分组，而非平铺的提交列表。
  • 示例 - 当版本变更行为时，提供CLI命令、配置片段、输出示例、Schema片段或前后工作流对比。
  • 可视化证据 - 当UI、CLI、仪表板、TUI或工作流更适合可视化理解时，提供截图、图表或输出捕获。
  • 重要性 - 日常使用中的实际影响。
请勿编造动机。若缺少ax会话证据，说明提交记录和变更文件能证明的内容，并缩小叙述范围。

4. Assets and rendering

4. 资源与渲染

Put website-visible release images here:
text
apps/site/public/releases/assets/
Reference them from release markdown:
md
![Focused release screenshot](/releases/assets/vX.Y.Z-topic.png)
The website release renderer supports headings, lists, links, bold scopes, fenced code blocks, and images. Use those instead of hand-written HTML.
将网站可见的版本图片放置在此处：
text
apps/site/public/releases/assets/
在版本markdown中引用它们：
md
![聚焦版本截图](/releases/assets/vX.Y.Z-topic.png)
网站版本渲染器支持标题、列表、链接、加粗范围、代码块和图片。请使用这些元素，而非手写HTML。

5. Verify

5. 验证

Run:
bash
bun run typecheck
cd site && bun run build
If the page changed, preview and smoke the specific version page:
bash
cd site
bun run preview -- --host 127.0.0.1 --port 4175
Check 
/changelog
and 
/changelog/vX.Y.Z
.
运行以下命令：
bash
bun run typecheck
cd site && bun run build
若页面有变更，预览并测试特定版本页面：
bash
cd site
bun run preview -- --host 127.0.0.1 --port 4175
检查
/changelog
和
/changelog/vX.Y.Z
页面。