docs-changelog

流程：更新新版本的变更日志

目标

规范根据自动生成的发布信息更新变更日志文件（latest.md、 preview.md、index.md）的流程。

输入

• version：发布版本字符串（例如，v0.28.0、 v0.29.0-preview.2）。
• TIME：发布时间戳（例如，2026-02-12T20:33:15Z）。
• BODY：原始 Markdown 发布说明，包含“What's Changed”部分和 “Full Changelog”链接。

latest.md 和 preview.md 的重点内容指南

• 目标是列出 3-5 个重点。
• 每个重点都必须以一个概括变更内容的粗体标题开头（例如，**New Feature:** A brief description...）。
• 优先总结新功能，而非修复错误或日常维护等其他变更。
• 在稳定版中，避免提及“实验性”或“预览中”的功能。
• 不要在这些重点中包含 PR 编号、链接或作者姓名。
• 请参阅 .gemini/skills/docs-changelog/references/highlights_examples.md 了解正确的风格和语气。

初始处理

1. 分析版本：根据 version 字符串确定发布路径。
   • 如果 version 包含“nightly”，停止。不做任何更改。
   • 如果 version 以 .0 结尾，遵循路径 A：新次要版本流程。
   • 如果 version 不以 .0 结尾，遵循路径 B：补丁版本流程。
2. 处理时间：将 TIME 输入转换为以下两种格式，以便后续使用： yyyy-mm-dd 和 Month dd, yyyy。
3. 处理正文：
   • 将收到的 BODY 内容保存到临时文件中以供处理。
   • 在临时文件的“What's Changed”部分中，将所有拉取请求 URL 重新格式化为以 PR 编号为文本的 Markdown 链接（例如， [#12345](URL)）。
   • 如果存在“New Contributors”部分，请将其删除。
   • 保留“Full Changelog”链接。此临时文件处理后的内容将在后续步骤中使用。

---

路径 A：新次要版本

如果版本号以 .0 结尾，请使用此路径。

**重要：**根据版本，必须选择遵循 A.1 稳定版或 A.2 预览版。不要遵循另一部分中的说明。

A.1：稳定版（例如，v0.28.0）

对于稳定版，你需要根据变更日志生成两种不同的摘要：用于主变更日志页面的简洁公告，以及用于特定版本页面的详细重点内容部分。

1. 为 index.md 创建公告：

   • 生成简洁的公告，总结最重要的变更。每条公告都必须以一个概括变更内容的粗体标题开头。
   • 重要：此公告的格式独特。你必须参考 docs/changelogs/index.md 中现有的公告以及 .gemini/skills/docs-changelog/references/index_template.md 中的示例。此格式包含 PR 链接和作者。仅使用 1 或 2 个 PR 链接和作者。
   • 将此新公告添加到 docs/changelogs/index.md 顶部。

2. 创建重点内容并更新 latest.md：

   • 按照上文“latest.md 和 preview.md 的重点内容指南”部分的要求， 生成完整的“Highlights”部分。
   • 使用 .gemini/skills/docs-changelog/references/latest_template.md 中的内容。
   • 将 version、release_date、生成的 highlights 以及临时文件中处理后的内容填入模板。
   • 完全替换 docs/changelogs/latest.md 的内容，换成填充后的模板。

A.2：预览版发布（例如，v0.29.0-preview.0）

1. 更新 preview.md：
   • 按照亮点编写指南，生成完整的“亮点”部分。
   • 从 .gemini/skills/docs-changelog/references/preview_template.md 获取内容。
   • 使用 version、release_date、生成的 highlights 以及临时文件中的处理后内容填充模板。
   • 完全替换 docs/changelogs/preview.md 的内容，换成填充后的模板。

---

路径 B：补丁版本

如果版本号不以 .0 结尾，请使用此路径。

重要提示： 根据版本号，你必须选择遵循 B.1（稳定版补丁）或 B.2（预览版补丁）。不要遵循另一节中的说明。

B.1：稳定版补丁（例如，v0.28.1）

• 目标文件：docs/changelogs/latest.md
• 对目标文件执行以下编辑：

  1. 更新主标题中的版本号。该行应为： # Latest stable release: {{version}}

  2. 更新发布日期。该行应为： Released: {{release_date_month_dd_yyyy}}

  3. 确定临时文件中是否存在“What's Changed”部分。 如果存在，继续执行第 4 步；否则，跳到第 5 步。

  4. 将临时文件中处理后的“What's Changed”列表前置到 latest.md 现有的“What's Changed”列表中。不要更改或替换现有列表，只在其开头添加内容。

  5. 在“Full Changelog”中，仅编辑 URL 的末尾。找到类似 ...{previous_version} 的 URL 最后一部分，并将其更新为 ...{version}。

     示例：假设补丁版本为 v0.29.1。将 Full Changelog: https://github.com/google-gemini/gemini-cli/compare/v0.28.2…v0.29.0 更改为 Full Changelog: https://github.com/google-gemini/gemini-cli/compare/v0.28.2…v0.29.1

B.2：预览版补丁（例如，v0.29.0-preview.3）

• 目标文件：docs/changelogs/preview.md
• 对目标文件执行以下编辑：

  1. 更新主标题中的版本号。该行应为： # Preview release: {{version}}

  2. 更新发布日期。该行应为： Released: {{release_date_month_dd_yyyy}}

  3. 确定临时文件中是否存在“What's Changed”部分。 如果存在，继续执行第 4 步；否则，跳到第 5 步。

  4. 将临时文件中处理后的“What's Changed”列表前置到 preview.md 现有的“What's Changed”列表中。不要更改或替换现有列表，只在其开头添加内容。

  5. 在“Full Changelog”中，仅编辑 URL 的末尾。找到类似 ...{previous_version} 的 URL 最后一部分，并将其更新为 ...{version}。

     示例：假设补丁版本为 v0.29.0-preview.1。将 Full Changelog: https://github.com/google-gemini/gemini-cli/compare/v0.28.2…v0.29.0-preview.0 更改为 Full Changelog: https://github.com/google-gemini/gemini-cli/compare/v0.28.2…v0.29.0-preview.1

---

收尾

• 完成更改后，如果 npm run format 失败，可能需要先运行 npm install，以确保所有格式化依赖均可用。 然后运行 npm run format，确保格式一致。
• 删除处理过程中创建的所有临时文件。