企业官网建设流程全解析

• 数据可视化
• 后端
• 前端

本指南完整讲解 Streamlit 仓库中.claude/skills/generating-changelog/SKILL.md所定义的技能：在任意两个 git tag（上一版本与新版发布）之间，自动抓取 PR 元数据、按标签分类、并生成符合 docs.streamlit.io 网站格式的发布说明。读者将掌握从输入校验、GraphQL 批量拉取、脚本分类、人工复审到最终文案撰写的完整流水线，可直接复用于 Streamlit 每次正式发布（含 patch 版本）的文档更新环节。

一、技能定位：网站 Changelog 与 GitHub Release Notes 的区别

Streamlit 的发布说明存在两种形态，由不同机制生成：

• GitHub Release 自动生成：由仓库的 .github/release.yml 定义标签到分类的映射，在 .github/workflows/release.yml 的"Create GitHub Release"步骤中通过 scripts/create_release.py 调用 GitHub 的generate-notesAPI 自动生成，无需人工干预。
• 网站 Changelog（本技能产出）：发布到 docs.streamlit.io 的 release notes 页面，需要以用户视角重写 PR 标题、归类到三级结构、附加 emoji 与 PR/issue 链接。generating-changelog技能只负责产出这第二种格式。

该技能以 Claude Code 风格斜杠命令触发，调用形式为：

/generating-changelog <previous-tag> <new-tag>

例如/generating-changelog 1.61.0 1.62.0。若只给一个 tag，则将其视为新版本 tag，并自动通过gh api repos/streamlit/streamlit/releases/latest获取上一版本 tag。

它在 Streamlit 发布流程中的位置，见 wiki/release-process.md：正式（非 patch）版本发布并确认 PyPI 可安装后，在streamlit/streamlit仓库先执行git fetch --tags，再调用本技能生成网站 changelog，随后把生成内容粘贴给streamlit/docs仓库的updating-docs-for-release技能完成文档 PR。技能名与调用示例均记录在 wiki/release-process.md 的"Update the documentation"小节中。

二、Step 1：输入校验与前置检查

技能的第一步是校验两个 tag：

1. 解析参数：第一个参数为上一发布版本，第二个为新发布版本。
2. 仅传一个 tag 时自动补全上一版本：

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

3. 严格校验两个 tag 都存在（使用精确引用，不做模式匹配）：

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

   该命令必须对每个 tag 都返回退出码 0。

4. 获取新版本的发布日期：

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

此逻辑与 scripts/changelog_fetch_prs.py 中的_validate_tag函数一一对应——脚本内部同样通过git rev-parse -q --verify refs/tags/<tag>校验，失败时向 stderr 打印错误并以退出码 1 终止。日期信息用于最终输出的_Release date: <Month Day, Year>_行。

三、Step 2：抓取 PR 数据

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

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

脚本（即 scripts/changelog_fetch_prs.py）的完整执行链路如下：

1. 用git log --oneline <prev-tag>..<new-tag>提取提交历史，通过正则\(#(\d+)\)收集 PR 编号并排序（_extract_pr_numbers）。
2. 按每批50 个 PR构造单个 GraphQL 查询（_build_graphql_query），查询字段包括number、title、body、labels（前 100 个）、author.login，以及closingIssuesReferences（前 10 个）及其 👍 反应计数。
3. 解析响应并写出work-tmp/pr-data.json——一个按 PR 编号排序的 JSON 数组，元素结构为：

{ "number": 14139, "title": "...", "body": "...", "labels": ["change:feature", "impact:users"], "author": "...", "related_issues": [{"number": 9836, "thumbs_up": 42}], "related_issues_truncated": false }

值得注意的实现细节：

• body字段被截断到前 2500 个字符（源码中的_BODY_MAX_CHARS = 2500），以保证输出文件体积可控。
• related_issues与 PR 元数据来自同一次批量 GraphQL 查询，避免逐 PR 的 N+1 请求；按 👍 数量降序排序，供后续 Highlights 候选排序参考。
• 容错机制：批量查询失败时逐条重试；若某编号"Could not resolve to a PullRequest"（非合法 PR），打印提示并跳过，不中断整体流程。

四、Step 3 & 4：过滤与分类

运行分类脚本：

uv run python scripts/changelog_categorize_prs.py

该脚本（scripts/changelog_categorize_prs.py）读取work-tmp/pr-data.json，应用以下规则后写出work-tmp/pr-categorized.json：

排除规则（noise）

• 机器人作者：dependabot、github-actions、snyk-bot、renovate、codecov 等（源码_BOT_AUTHORS集合）。
• 发布/版本类噪声：标题匹配release/\d+\.\d+、merge.*release、bump version、version bump、docstrings for等模式（_RELEASE_PATTERNS）。
• 仅内部影响的 PR：带impact:internal且不带impact:users——这包含带有change:*标签的内部功能 PR（如 e2e 基础设施、CI 工作流、agent 技能等）。这一判断逻辑对应 GitHub 侧的 .github/release.yml 中exclude.labels的impact:internal。

外部贡献者识别

每个未被排除的 PR 都会带上is_external布尔字段：作者匹配sfc-gh-*前缀或已知内部作者集合（如 kmcgrady、lukasmasuch、mayagbarnes、raethlein、vdonato，见源码_KNOWN_INTERNAL_AUTHORS）的标记为is_external: false，其余为true。分类汇总输出会单独列出外部贡献者清单，用于在 changelog 中正确署名，无需再去查 GitHub 个人主页。

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

没有任何impact:*或change:*标签的 PR 会被标记为unlabeled，交由人工复审。源码中categorize_prs函数的实现顺序与上表完全一致：先查change:breaking，再change:feature、change:bugfix，然后impact:users or has_change，最后落入unlabeled。

需要强调：这些脚本分类只是分诊用的中间分组，网站 changelog 并没有 "Breaking Changes" 或 "New Features" 小节。所有条目最终都会映射到下面的三个网站层级中；破坏性变更、弃用与移除会以合适的 emoji 折叠进 Notable Changes 或 Other Changes（见 Step 6 的 emoji 规则）。

映射到三个网站层级

• Highlights（可选——没有符合条件的 PR 时整个小节省略）：每版本仅 0–4 条，只保留真正的重大用户侧能力，例如全新的 widget-to-URL-params 体系、动态容器控制这类全新能力，或解锁新工作流的重要新 API 参数、重大破坏性变更。增量改进、新配置项、既有命令新增参数都不应进入 Highlights。某些版本（如 patch 版本）根本没有 Highlights 小节。
• Notable Changes：其余的功能、有影响力的改进、新参数、未被提升到 Highlights 的破坏性变更。
• Other Changes：Bug 修复、文档、杂务、小改进。

标签体系的来源可参见 wiki/pull-requests.md：所有 PR 必须带一个影响标签（impact:users或impact:internal）加一个变更类型标签（change:feature、change:bugfix、change:chore、change:refactor、change:docs、change:spec、change:other）。该要求在 CI 中由 .github/workflows/require-labels.yml 强制校验——每个 PR 必须恰好有一个change:*标签和一个impact:*标签（change:spec可豁免impact:*）。这些约定正是分类脚本能够可靠工作的前提。

五、Step 5：提交分类结果供人工确认

在生成最终输出之前，必须先向用户展示一份摘要，包括：

1. PR 总数及每个分类的数量；
2. 拟进入 "Highlights" 层级的 PR 清单——允许用户提升/降级；
3. Step 3 中标记的未打标签 PR，附建议分类；
4. 对处于 Highlights 边缘的候选，可将related_issues中关联 issue 的 👍 计数作为排序信号之一（不是唯一信号）；
5. 脚本识别出的外部贡献者（来自is_external字段）——sfc-gh-*或已知内部作者无需查 GitHub 主页，只需核对边界情况；
6. 请用户确认或调整后再继续。

注意：内部专用功能 PR（e2e 基础设施、CI 工作流、agent 技能等）已被分类脚本排除，无需手动过滤。

在用户确认之前，不得进入 Step 6。这一步体现了人工把关与自动化结合的设计：脚本负责机械性的抓取和初步归类，而层级归属（尤其 Highlights）最终由发布负责人裁定。

六、Step 6：阅读 PR 描述并生成输出

对work-tmp/pr-categorized.json中每个用户侧 PR，写 changelog 条目前先读它的body字段。PR 描述是"实际发生了什么"的首要事实来源——仅凭标题可能不精确。重点关注描述开头的总结段落，忽略 checklist、评审意见和截图说明。

条目长度：每条保持一句话，最多两句，只传达高层思想——改了什么以及为什么对用户重要。不要枚举子功能、实现细节、参数列表或边界行为，那些细节属于 API 文档。

生成文件位于work-tmp/目录：work-tmp/changelog-website-<new-tag>.md。

各分类的文案风格

• Highlights：宣告式口吻——"Introducing..."、"Announcing..."。PR 链接可酌情包含或省略。
• Features / 新参数（Notable Changes）：用户视角——"You can now..."、"st.foohas a newbarparameter to..."、"st.foosupports..."
• Bug 修复：统一以 "Bug fix:" 前缀开头——"Bug fix:st.spinneravoids a race condition..."
• 弃用/移除：平实描述并配特定 emoji（见下方 emoji 列表）。
• 其他非 bug 条目：一般现在时平实描述，无前缀。

格式化规则

• 改写前先去掉 PR 标题中的[fix]/[feat]/[chore]/[docs]前缀；
• Emoji 规则：
  • Bug 修复按序轮换使用虫类 emoji：🐛、🦋、🪲、🐜、🐝、🐞、🕷️、🪳、🪰、🦠、🦟、🦂、🦗、🕸️、🐌、🦎、🦀、👽、👻；
  • 移除用 👻，弃用用 ☠️，考虑中但未移除的用 💩；
  • 非 bug 条目只能使用以下批准调色板中的 emoji（要轮换使用，不要连续重复）：

当调色板没有合适 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` — a widget that lets you do something amazing ([#14200](https://github.com/streamlit/streamlit/pull/14200)). **Notable Changes** - 📊 `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 标题）。

七、Step 7：最终总结

写入文件后，向用户打印：

• 生成 changelog 的文件路径；
• 每个分类的 PR 数量；
• 提醒在发布前复核该文件。

八、关键参考与联动资源

• .github/release.yml——标签到分类的权威映射（同时用于 GitHub 自动生成的 release notes），是分类脚本与网站 changelog 的共同基础。
• scripts/changelog_fetch_prs.py——PR 元数据抓取实现（tag 校验、git logPR 编号提取、GraphQL 批量查询、容错重试）。
• scripts/changelog_categorize_prs.py——过滤与分类实现（bot/内部/发布噪声排除、is_external识别、优先级分类、控制台摘要输出）。
• wiki/pull-requests.md——PR 标签约定（impact:*+change:*），是分类数据质量的上游保证。
• .github/workflows/require-labels.yml——CI 中强制 PR 标签合规的校验逻辑。
• wiki/release-process.md——技能在正式发布流程中的调用时机与上下文（/generating-changelog <previous-version-tag> <new-version-tag>示例）。
• .github/workflows/release.yml 与 scripts/create_release.py——GitHub 自动生成 release notes 的实现，用于与网站 changelog 区分理解。

九、完整流程一图流

/generating-changelog <prev-tag> <new-tag> │ ▼ Step 1 校验 tag（git rev-parse）、补全上一版本（gh api）、取发布日期 │ ▼ Step 2 uv run python scripts/changelog_fetch_prs.py <prev> <new> └─ git log 提取 PR 编号 → GraphQL 每批 50 个批量查询 └─ 产出 work-tmp/pr-data.json（body 截断 2500 字符，related_issues 带 👍 数） │ ▼ Step 3 uv run python scripts/changelog_categorize_prs.py └─ 排除 bot / 发布噪声 / 仅内部 PR └─ 按 change:* 优先级分类 + is_external 标记 └─ 产出 work-tmp/pr-categorized.json + 控制台摘要 │ ▼ Step 5 向用户展示分类摘要（Highlights 候选、unlabeled、外部贡献者）→ 等待确认 │ ▼ Step 6 逐条阅读 PR body → 按三层级 + emoji + 链接规则撰写 └─ 产出 work-tmp/changelog-website-<new-tag>.md │ ▼ Step 7 打印文件路径、分类计数、发布前复核提醒

这套流水线的设计要点可以归纳为三点：自动化承担机械劳动（抓取、去噪、初步分类），脚本分类只是中间分诊而非最终结构（最终层级由人工结合 PR 描述与 👍 信号裁定），文案质量靠规范约束（一句话原则、调色板 emoji、统一链接与署名格式）。掌握它，即可在任何一次 Streamlit 版本发布时快速产出高质量、可直接发布到 docs.streamlit.io 的网站 changelog。

• 数据可视化
• 后端
• 前端