Skip to content

feat(release): user-facing bilingual digest for release notes - #9216

Merged
wenshao merged 8 commits into
QwenLM:mainfrom
wenshao:feat/user-facing-release-notes
Aug 17, 2026
Merged

wenshao merged 8 commits into
QwenLM:mainfrom
wenshao:feat/user-facing-release-notes

Conversation

@wenshao

@wenshao wenshao commented Aug 15, 2026

Copy link
Copy Markdown
Collaborator

What this PR does

Stable release notes currently read as a developer-facing list of pull requests bucketed by commit type. This PR turns the finalize step into a user-facing digest: the model now groups the release's changes into a few capability themes, each with a short intro and plain-language items, and the full pull-request list moves into a collapsed appendix with uniformly normalized titles. Highlights and themes are mirrored into a Chinese digest below a divider, and screenshots already present in merged pull-request bodies are attached to their digest items (host allowlist, capped per entry and per release). The changelog generator accepts the new marker version and embeds the digest, unwrapping the collapsed appendix and dropping images so CHANGELOG.md stays plain text. Every model failure keeps a working output: a failed themes call falls back to today's layout, invalid translations fall back to English with a run warning, and a model-less run reproduces today's notes byte for byte.

Why it's needed

The current notes are hard for users to scan: entries are grouped by change type rather than by the area a user cares about, styles mix whenever a model summary falls back to a raw feat(scope): title, and there is no Chinese version despite a large Chinese-speaking user base. UI changes also ship without visuals even when the pull request already carries Before/After screenshots. Measured on the last two stable releases, only about 4% of release pull requests carry body images, so screenshots are best-effort decoration while the themed bilingual digest is the structural improvement.

Reviewer Test Plan

How to verify

  1. Unit suites (new and updated coverage for extraction, validation, bilingual rendering, fallbacks, and changelog embedding): npx vitest run --config ./scripts/tests/vitest.config.ts scripts/tests/generate-release-notes.test.js scripts/tests/generate-changelog.test.js scripts/tests/ai-release-notes-workflow.test.js. Expected: everything green except five pre-existing appendDegradedStepSummary failures that reproduce on unmodified main (verified in a temporary worktree).
  2. No-model fallback regression: env -u OPENAI_API_KEY -u OPENAI_BASE_URL -u OPENAI_MODEL node scripts/generate-release-notes.js --repo=QwenLM/qwen-code --tag=v0.21.12 --previous-tag=v0.21.11 --target=v0.21.12 --dry-run. Expected: today's v1 layout, byte-identical to the same command on main (diffed).
  3. Model-driven path (requires OPENAI_API_KEY / OPENAI_BASE_URL / OPENAI_MODEL): the same command with model env vars set. Expected: v2 marker, bilingual highlights, themed sections with intros, a 中文摘要 block, a collapsed appendix with normalized titles and author credits, and the Full Changelog trailer. Observed locally with qwen3.8-max: one summaries batch hit the 180s client timeout once and recovered on retry; one oversized summary degraded to its normalized title with a ::warning:: — both degradation paths exercised for real.
  4. Changelog regression: node scripts/generate-changelog.js --dry-run — output is unchanged while all live releases are v1; the v2 transform is covered by the new unit test.

Evidence (Before & After)

Before (today, v0.21.12): ## Highlights followed by a ## Complete Change List wall of ~50 type-bucketed entries. After (dry-run of the v0.21.12..main range with qwen3.8-max):

## Highlights
- Deny-by-default guardrails for the qwen-autofix footprint gate... (#9156)
...
## Autofix guardrails
qwen-autofix now enforces a deny-by-default footprint check...
- autofix: deny-by-default footprint gate and positional window censuses ([#9156](...))
---
## 中文摘要
### 亮点
- qwen-autofix 默认启用基于白名单的足迹门禁... (#9156)
### Autofix 安全管控
qwen-autofix 现强制执行默认拒绝的足迹检查...
<details><summary>Complete Change List (2 pull requests)</summary>

#### Features
- autofix: deny-by-default footprint gate and positional window censuses ([#9156](...)) by @doudouOUC
...
</details>

Tested on

OS Status
🍏 macOS
🪟 Windows N/A
🐧 Linux N/A

Environment (optional)

Node 22, scripts run directly with node, gh authenticated read-only against QwenLM/qwen-code; all runs were --dry-run (nothing published).

Risk & Scope

  • Main risk or tradeoff: the digest depends on the release workflow's configured model answering three JSON calls; slower models can hit per-call timeouts. The existing retry/backoff, circuit breaker, and fallback ladder absorb this — worst case is today's v1 layout with ::warning:: annotations, never a failed release step.
  • Not validated / out of scope: no workflow or package changes; nightly/preview notes unaffected; a full 50-PR-range model run was not forced locally because the local model's thinking mode stalled on some PR bodies (small-range E2E passed; CI's own model configuration owns production runs).
  • Breaking changes / migration notes: none. All existing v1 releases keep rendering exactly as before in CHANGELOG.md; the v2 marker only appears starting with the first release finalized after this lands.

Linked Issues

N/A — maintainer-requested readability improvement.

中文说明

本 PR 做了什么

稳定版的 Release Notes 目前是按 commit 类型分桶的 PR 列表,属于开发者视角。本 PR 把 finalize 步骤改造成面向用户的摘要:模型将本次发布的变更归纳为若干能力主题,每个主题配一句简短导语和通俗条目,完整 PR 列表移入折叠附录并统一归一化标题。Highlights 与主题在分隔线下方镜像为「中文摘要」;已合并 PR body 中现成的截图会挂到对应摘要条目下(host 白名单、单条目与单 release 数量上限)。CHANGELOG 生成器接受新版 marker 并嵌入摘要,同时展开折叠附录、剥离图片,保证 CHANGELOG.md 仍是纯文本。所有模型失败路径都有可用输出:themes 调用失败回退到今天的版式,单条翻译失败回退英文并发 ::warning::,无模型配置时的输出与现状逐字节一致。

为什么需要

现有 Release Notes 对用户不友好:条目按变更类型而非用户关心的领域分组;模型摘要回退为原始 feat(scope): 标题时风格混杂;中文用户量大却没有中文版。UI 变更即使 PR 里已带 Before/After 截图,发布说明里也看不到。对最近两个稳定版的实测显示仅约 4% 的 release PR body 带图,因此截图是尽力而为的装饰,主题式双语摘要才是结构性改进。

审查者测试计划

验证方式与英文版相同:单测套件全绿(除 main 上已存在、与本改动无关的 5 个 appendDegradedStepSummary 失败);无模型 dry-run 与 main 上的输出逐字节一致;配置 OPENAI_* 环境变量后的 dry-run 产出 v2 双语主题摘要(本地用 qwen3.8-max 实测,真实触发过一次超时重试与一次超长摘要降级);generate-changelog.js --dry-run 输出不变(现网 release 均为 v1,v2 转换有新单测覆盖)。

风险与范围

主要风险:摘要依赖 release workflow 配置的模型完成三次 JSON 调用,慢模型可能触发单次调用超时——由既有的重试/退避、断路器与回退阶梯兜底,最差结果是回退到今天的 v1 版式并输出 ::warning::,不会导致发布步骤失败。未验证/超出范围:不改 workflow 与包;nightly/preview 不受影响;50 个 PR 的完整范围未用本地模型强制跑完(thinking 模式在个别 PR 内容上长时间无响应),小范围 E2E 已通过,生产由 CI 自己的模型配置运行。无破坏性变更:所有已发布的 v1 release 在 CHANGELOG.md 中渲染完全不变,v2 marker 只在本 PR 合入后的首个 finalize 发布中出现。

关联 Issue

无——maintainer 提出的可读性改进需求。

Loading
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

autofix/takeover Summon the autofix loop to manage this PR (remove to release; needs triage+)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants