generating-changelog

生成更新日志

在两个 git 标签之间生成可直接发布的网站更新日志（docs.streamlit.io 格式）。使用 PR 标签（impact:users、impact:internal、change:*）进行分类，并将 PR 标题改写为对用户友好的描述。

GitHub release 更新日志由 .github/release.yml 自动生成——此 skill 仅生成网站格式。

用法： /generating-changelog <previous-tag> <new-tag>（例如 /generating-changelog 1.44.1 1.45.0）

如果只给出一个标签，则将其视为新 release 标签，并自动获取上一个标签。

步骤 1：验证输入

• 从用户参数中解析两个标签。第一个 = 上一个 release，第二个 = 新 release。
• 如果只给出一个标签，则获取上一个标签：

  gh api repos/streamlit/streamlit/releases/latest --jq '.tag_name'
  

• 使用精确引用（不使用模式匹配）验证两个标签均存在：

  git rev-parse -q --verify "refs/tags/<tag>" > /dev/null
  

  此命令对每个标签都必须成功（退出码为 0）。
• 从较新的标签获取 release 日期：

  git log -1 --format=%ai <new-tag>
  

步骤 2：获取 PR 数据

运行获取脚本，从 git log 中提取 PR 编号，并通过 GitHub GraphQL 批量获取元数据：

uv run python scripts/changelog_fetch_prs.py <prev-tag> <new-tag>

这会生成 work-tmp/pr-data.json——一个由 {number, title, body, labels, author, related_issues, related_issues_truncated} 对象组成的 JSON 数组，按 PR 编号排序。body 字段包含 PR 描述的前 2500 个字符。

related_issues 来自同一个批量 GraphQL 查询（没有按 PR 的 N+1 请求），包含关联的 issue 编号以及 👍 数量：

"related_issues": [{"number": 9836, "thumbs_up": 42}]

步骤 3 和 4：筛选与分类

运行分类脚本以排除噪声，并按标签对 PR 进行分类：

uv run python scripts/changelog_categorize_prs.py

该脚本读取 work-tmp/pr-data.json，应用以下规则，并写入 work-tmp/pr-categorized.json：

排除项： 机器人作者、release/version/docstring PR、仅内部 PR（impact:internal 且不含 impact:users — 这包括带有 change:* 标签的内部功能）。

外部贡献者： 每个未被排除的 PR 都包含一个 is_external 布尔字段。作者匹配 sfc-gh-* 或已知内部集合的标记为 is_external: false；其余全部为 is_external: true。摘要输出会单独列出外部贡献者 — 可用它来归属贡献，而无需查询 GitHub 个人资料。

脚本类别（按标签优先级：breaking > feature > bugfix > 其他）：

标签	脚本类别
change:breaking	破坏性变更
change:feature	新功能
change:bugfix	Bug 修复
impact:users 或无法识别的 change:* 标签	其他变更

没有 impact:* 或 change:* 标签的 PR 会被标记为 unlabeled，供用户审核。

注意：change:* 标签通常是 release 标签规范所要求的。"其他变更" 回退项是针对 impact:users PR 以及未被 breaking/feature/bugfix 覆盖的非标准 change:* 值的防御性兜底。

重要： 这些脚本类别是用于分诊的中间分组。网站 changelog 没有 "破坏性变更" 或 "新功能" 部分。所有条目都会被映射到下面的三个网站层级中。破坏性变更、弃用和移除会归入 Notable Changes 或 Other Changes，并使用适当的 emoji（见步骤 6）。

映射到三个网站层级：

• Highlights（可选 — 当没有符合条件的 PR 时完全省略）：每个 release 仅 0–4 项。保留给真正重大的面向用户的新增内容：全新能力（例如新的 widget-to-URL-params 系统、动态容器控制）、能解锁新工作流的重大新 API 参数，或重大破坏性变更。渐进式改进、新配置选项以及现有命令上的附加参数应归入 Notable Changes，而非 Highlights。有些 release（例如补丁版本）完全没有 Highlights 部分。
• Notable Changes：剩余功能、有影响力的改进、新参数、未提升到 Highlights 的破坏性变更
• Other Changes：Bug 修复、文档、杂项、小幅改进

步骤 5：呈现分类以供审核

在生成最终输出之前，向用户呈现摘要：

1. PR 总数及每个类别的数量
2. 建议归入 "Highlights" 层级的 PR 列表 — 允许用户提升/降级
3. 步骤 3 中标记的任何 unlabeled PR，附建议分类
4. 对于边缘性的 Highlights 候选，可将 related_issues 中关联 issue 的 👍 数作为一个优先排序信号（不是唯一信号）
5. 脚本识别出的外部贡献者（来自 is_external 字段）— 核实任何边缘情况，但无需为 sfc-gh-* 或已知内部作者查询 GitHub 个人资料
6. 请用户确认或调整后再继续

注意：仅内部功能 PR（例如 e2e 基础设施、CI 工作流、Agent 技能）已被分类脚本排除。你应当无需手动筛选这些。

在用户确认之前，不要进入步骤 6。

第 6 步：读取 PR 描述并生成输出

对于 work-tmp/pr-categorized.json 中每个面向用户的 PR，在编写更新日志条目之前先读取其 body 字段。将 PR 描述作为实际变更内容的主要事实来源——仅凭标题可能不够准确。重点关注正文开头的概述段落；忽略检查清单、审阅者备注和截图部分。

条目长度： 每个条目控制在一句话，最多两句。只捕捉高层要点——发生了什么变化，以及为什么这对用户重要。不要罗列子功能、实现细节、参数列表或边界情况行为。这些细节属于 API 文档。

在 work-tmp/ 目录中生成文件：work-tmp/changelog-website-<new-tag>.md

按类别划分的条目写作风格

• Highlights：公告式语气——"Introducing..."、"Announcing..."。PR 链接可自行决定是否包含。
• Features / new parameters（Notable Changes）：用户视角的语气——"You can now..."、"st.foo has a new bar parameter to..."、"st.foo supports..."
• Bug fixes：始终以 "Bug fix:" 为前缀——"Bug fix: st.spinner avoids a race condition..."
• Deprecations/removals：使用特定 emoji 的平实描述（见下方 emoji 列表）。
• Other non-bug entries：使用一般现在时的平实描述，无前缀。

格式规则

• 重写 PR 标题前，先移除 [fix]/[feat]/[chore]/[docs] 前缀
• Emoji：
  • Bug 修复轮换使用以下昆虫/bug emoji：🐛、🦋、🪲、🐜、🐝、🐞、🕷️、🪳、🪰、🦠、🦟、🦂、🦗、🕸️、🐌、🦎、🦀、👽、👻
  • 移除使用 👻，弃用使用 ☠️，考虑中移除使用 💩
  • 非 bug 条目仅使用以下已批准 emoji 集合中的 emoji（要多样化使用，不要连续重复）。
    • UI/布局/设计：🎨、📐、🖼、🧩、📏、💅、🖌、🎛、🎚、🔲、🌈、🪄
    • 数据/图表/表格：📊、📈、📋、🔢、🔣、📒、📃、📄
    • 性能/速度：⚡、🚀、⏱、⏩、⏳、🏎
    • 安全/认证：🔒、🔐、🔏、🛡、🔑、👮、🥷
    • 配置/设置：⚙、🔧、🛠、⚒、🧰、⛏、🔩
    • 链接/导航：🔗、🧭、➡、⬆、⬇、🔝、🚪、🛣、↩
    • 搜索/可见性：🔍、🔎、👀、🕵
    • 包/依赖：📦、🔤、📥、📤、💿、💾、💽
    • 新功能/亮点：✨、🎯、🆕、🍿、🎁、🎈、🎊、⭐、🌟、🆙
    • 文本/内容/文档：✍、📝、📜、📖、📘、📚、✏、✒、🖊、🖋
    • 通知/消息：🔔、📣、💬、📨、📩、📬、🛎
    • 状态/连接/同步：💓、🔀、🔄、🔁、📶、🔌、⛓
    • 媒体/显示：📷、📸、📹、📺、🎥、🎤、🎵、🎶、🎹、🖥
    • 文件/存储：📁、📂、🗂、🗃、🗑、📌、📍、🏷、🗜
    • 用户/身份：👤、👥、🧑、👋、🤝、👑
    • 错误/警告：🚨、🚩、⚠、🛑、❌、❓、🚧
    • 测试/科研：🧪、⚗、🔭、🧠
    • 杂项对象：💡、💎、💪、💯、💰、💻、💼、⌨、📱、📲、🖨、🖱、📞、🗝、🖇、✂、➕、🪜、🪧、🏗、🏠、🏢、🧱、🪵
    • 趣味/创意：🍔、🍞、🍪、🍰、🎩、🎫、🏁、🏃、🏄、🏋、🏓、🏹、🐍、🐙、🦊、🦐、🤖、🤹、🥸、🧞、🛸、🛹、🪗、🪆、🚇、🚒、🚣、🌱、🌐、🗺、🗻
  • 当没有合适的集合内 emoji 时，默认使用 ✨
• st.* 命令引用：使用反引号格式，并链接到对应的 API 文档子类别路径：st.image、st.dataframe。仅链接命令的首次/主要提及。链接在 Notable Changes 中比在 Other Changes 中更常见。
• PR 与 issue 链接：适用时同时包含 PR 链接和相关 issue 链接。格式：([#14139](https://github.com/streamlit/streamlit/pull/14139), [#9836](https://github.com/streamlit/streamlit/issues/9836))。PR 使用 /pull/，issue 使用 /issues/。
• 标点：每个条目在 PR/issue 链接的右括号后以句号结尾。
• 贡献者署名：对外部（非 Snowflake）贡献者进行署名。在链接文本中使用 [username]（不带 @ 前缀），放在右括号和句号之后：([#NNNNN](https://github.com/streamlit/streamlit/pull/NNNNN)). Thanks, [username](https://github.com/username)！
• 多 PR 分组条目：对于复杂的多 PR 功能，使用以冒号结尾的父级项目符号，然后使用缩进的子项目符号：

  - 🎨 Main feature description:
      - Sub-detail or sub-command ([#NNNNN](https://github.com/streamlit/streamlit/pull/NNNNN)).
      - Another sub-detail ([#MMMMM](https://github.com/streamlit/streamlit/pull/MMMMM)).
  

输出结构

## **Version <new-tag>**

_Release date: <Month Day, Year>_

**Highlights**

- 🍿 Introducing [`st.new_thing`](/develop/api-reference/widgets/st.new_thing) — a widget that lets you do something amazing ([#14200](https://github.com/streamlit/streamlit/pull/14200)).

**Notable Changes**

- 📊 [`st.dataframe`](/develop/api-reference/data/st.dataframe) has a new `selection_mode` parameter that lets you configure row and column selection behavior ([#14139](https://github.com/streamlit/streamlit/pull/14139), [#9836](https://github.com/streamlit/streamlit/issues/9836)).
- ☠️ `st.legacy_thing` is deprecated and will be removed in a future version. Use `st.new_thing` instead ([#14050](https://github.com/streamlit/streamlit/pull/14050)).
- 🔑 App menu redesign:
  - New "Settings" option in the app menu ([#14100](https://github.com/streamlit/streamlit/pull/14100)).
  - Reorganized menu items for better discoverability ([#14101](https://github.com/streamlit/streamlit/pull/14101)).

**Other Changes**

- 🐛 Bug fix: `st.spinner` avoids a race condition when used right before a cache miss ([#13849](https://github.com/streamlit/streamlit/pull/13849), [#13634](https://github.com/streamlit/streamlit/issues/13634)).
- 🦋 Bug fix: `st.number_input` no longer resets to default when the step value changes ([#14125](https://github.com/streamlit/streamlit/pull/14125)). Thanks, [contributor](https://github.com/contributor)!
- 🪲 Bug fix: Fixed a layout shift in `st.columns` when using `gap="small"` ([#14080](https://github.com/streamlit/streamlit/pull/14080)).

当发布没有 Highlights 时，完全省略该部分（不要包含空的 Highlights 标题）。

第 7 步：最终总结

写入文件后，打印：

• 生成的 changelog 的文件路径
• 各分类的 PR 数量
• 发布前审查该文件的提醒

关键参考

• .github/release.yml — 规范的标签到分类映射（也用于自动生成的 GitHub 发布说明）
• 网站 changelog 格式参考：https://docs.streamlit.io/develop/quick-reference/release-notes
• 示例文档 markdown 文件（风格参考）：https://raw.githubusercontent.com/streamlit/docs/997b19a5eda68b72ce091d69be9d6921a37e3da0/content/develop/quick-references/release-notes/2026.md