企业官网建设流程全解析

• 开发工具
• 后端

从NEWS.md到桌面端首发弹窗：一条面向发布团队的编辑流水线

一、这篇指南讲什么

本指南面向 RStudio 仓库的发布维护者与贡献者，完整讲解「为 RStudio Desktop 的What's New弹窗填充发布内容」的端到端流程：从核对当前分支与版本、定位发布内容目录，到筛选NEWS.md中的条目、按桌面用户视角撰写页面、执行验证测试，再到提交并打开 PR 的完整链路。

读完本文，你将掌握：

1. 版本与目录定位：如何把version/RELEASE中的花朵名（如Autumn Hawkbit）转换为 slug，并定位到src/node/desktop/src/assets/whats-new/<slug>/index.html；
2. 条目筛选标准：四条核心过滤规则（桌面用户 vs 管理员、用户 vs 开发团队、功能增强 vs 修复、弃用与移除），以及两条辅助判断（捆绑依赖、重命名）；
3. 页面撰写规范：加粗短标签 + 一到三句现在时陈述的写法、>/—/<code>等转义要求，以及固定的Fixes结尾段；
4. 验证与查看：npm test中的 what's new content validation 测试、RSTUDIO_SHOW_WHATS_NEW=1等环境变量、以及Help > What's New的预览方式；
5. 提交规范：提交信息模板、PR 正文应包含的取舍说明、以及里程碑匹配原则。

二、背景：What's New 页面是什么

该页面是每个 RStudio Desktop 发布版本在用户升级后首次启动时展示一次的功能公告窗口。它只存在于桌面版，RStudio Server 永不展示该窗口。页面按发布版本逐一存放于 src/node/desktop/src/assets/whats-new 目录，每个版本对应一个子目录：

whats-new/ ├── whats-new-base.css # 共享基础样式 ├── README.md # 目录布局、head 标签与样式类的权威说明 ├── globemaster-allium/ # "Globemaster Allium" 版本内容 │ ├── index.html │ └── images/ # 可选图片 │ └── feature-screenshot.png └── <next-release-slug>/ └── index.html

当前仓库正处在2026.10.0 "Blue Mistflower"（Daily 构建）周期，其内容页位于 blue-mistflower/index.html。各历史版本页面（autumn-hawkbit、golden-wattle 等）则构成真实的「风格样板」。

2.1 窗口的运行时结构

从源码看，What's New 窗口是一个无边框 Electron 子窗口：外层 host 页面提供固定头部（发布名与版本）、滚动 iframe 与底部关闭按钮，whats-new-host.html 中 iframe 通过../assets/whats-new/${release}/index.html相对路径加载版本内容页。窗口在showWhatsNewWindow()（whats-new-window.ts）中被创建为 900×825 的模态窗口，并施加了多项安全约束：

• 通过createLocalUrlChecker（whats-new-utils.ts）限定只有 host 页面目录与发布内容子目录内的 URL 才算本地导航，其余http(s)一律交给系统浏览器；
• 拦截主框架与子框架导航、把http(s)链接preventDefault后交给shell.openExternal；
• 用before-input-event实现 iframe 内按Escape也能关闭窗口；渲染进程崩溃或失去响应时销毁窗口，并跳过onClose（避免把异常关闭记成「已看过」）。

三、Step 1：核对起始分支

动手编辑前，先用 git 确认当前所在分支：

git branch --show-current

• 若输出是main、master或rel-*，先创建功能分支再编辑：feature/<slug>-whats-new；
• 若已在一个工作分支上，保持现状即可。

四、Step 2：定位发布版本与内容目录

cat version/RELEASE version/CALENDAR_VERSION version/PATCH

• version/RELEASE存放花朵名（flower name），例如Autumn Hawkbit或当前周期内的Blue Mistflower；
• 将花朵名 slug 化：转小写、去撇号、其余用连字符连接（Autumn Hawkbit→autumn-hawkbit），得到内容目录：

src/node/desktop/src/assets/whats-new/<slug>/index.html

该文件通常在发布分支创建时已经以占位条目（placeholder）生成。若不存在，则需依据 whats-new/README.md 中的模板创建——该 README 是目录布局、必需<head>标签与可用 CSS 类的权威来源。

slug 转换的源码佐证：toReleaseSlug()（whats-new-utils.ts）实现了与 README 一致的算法——toLowerCase()→ 去掉'→ 把非[a-z0-9]的连续字符替换为单个-→ 去除首尾连字符。单元测试 whats-new-utils.test.ts 覆盖了这些边界情形，例如"King's Crown"→kings-crown、'Sea Holly (v2)'→sea-holly-v2。

动笔前务必通读最近两到三个版本的index.html（globemaster-allium、autumn-hawkbit、pacific-dogwood 等）。它们是真实的风格指南——比任何文字描述都更准确地展示了条目应有的信息密度与措辞风格。

五、Step 3：通读本版本的 NEWS.md

仓库根目录的 NEWS.md 只存放进行中的发布条目；早期版本归档于 version/news/os/。必须读完整文件——值得展示的条目绝不局限于### New标题之下，### Fixed中按体验判断属于增强的条目、### Deprecated / Removed中的移除项都是候选。

六、Step 4：筛选条目（全文核心）

页面只列出终端用户会关心的新功能与增强——除此之外一概不列。四条过滤规则按「改变答案的频率」排序：

6.1 受众是桌面用户，不是管理员

What's New 窗口只随 RStudio Desktop 发布，RStudio Server 从不展示它。因此凡是面向部署配置者的内容一律砍掉：会话选项、rserver/rsession命令行标志、服务器配置文件、launcher 行为，以及仅在 Server 下才显现的修复。这类条目往往是### New下最大的一批——恰恰是首先要删的。

仓库实证：对照 NEWS.md 与 blue-mistflower/index.html，可以看到 #18899（Server 重启卡顿）、#18864（Server 下载权限崩溃）、#18718（Server 启动挂起）等条目均未进入页面，而它们都是### Fixed下的真实修复——受众不是桌面用户。

6.2 受众是用户，不是我们

砍掉构建工具、CI、代码签名、打包内部细节、崩溃上报管道与测试基础设施。

仓库实证：#18803「RStudio Desktop 记录渲染器/GPU/utility 进程失败日志以帮助诊断崩溃」属于崩溃上报管道，未入选；而同样为开发者向的#18739（启动优化）与#18738（安装体积减小）却入选了——因为用户能直接感受到结果。

6.3 只列功能与增强，不列修复

普通 bug 修复属于发布说明，页面结尾的Fixes段会链接到它（见 Step 5）。例外是：措辞像修复、但读起来是改进的条目——一次性能优化、或对上版本功能的延伸。判断依据是用户体验：

• "searching and scrolling are faster"（搜索与滚动更快）——无论它在哪个标题下，都是增强；
• "fixed a crash when …"——不是。

仓库实证：NEWS.md 中 #11622（成功渲染后最小化的 Console 保持最小化）与 #16386（滚动回看上限立即生效）虽在### Fixed下，但用户体验上是改进，与页面上的「Console 相关改进」方向一致；而 #8729（数据目录文件导致启动失败）、#18735（组策略禁用命令提示符导致 Windows 无法启动）等纯修复被留在发布说明中。

6.4 弃用与移除要算数

若### Deprecated / Removed点名的东西是用户依赖的——某个发布目的地消失、某个工作流退役——应在功能列表之后给它们独立的简短Deprecated段。用户对「东西要消失」的警告需求，比对「东西新增」的需求更强；而发布说明链接很容易被忽略。

仓库实证：2026.09 周期的 autumn-hawkbit/index.html 为 RPubs 与 ShinyApps.io 发布目的地单列了Deprecated段并附迁移指南；当前 blue-mistflower/index.html 也为「Uninstall Posit Assistant 命令被移除」单列了Deprecated段。

6.5 两个较小的判断

• 捆绑依赖：组件版本号升级只在用户能注意到时才值得一行——例如新的 Quarto 次要版本，而不是某个语言服务器的补丁版。务必对照上一版本的### Dependencies列表（在 version/news/os/ 下）确认它确实是本周期新引入的；那些列表只记录变更项，所以「没有某行」不代表「版本没变」。
• 重命名：用户可见的产品/服务重命名应上页面，避免用户对新名字困惑。一行足够。仓库实证：autumn-hawkbit 页面中的 "Posit AI Pass" 改名条目正是这种一行重命名。

七、Step 5：撰写条目

每条条目遵循固定结构：加粗的短标签开头，然后一到三句、现在时的平实陈述，并匹配前几版页面的散文密度。

7.1 头条级条目要读实现 commit

对任何「头条级」功能，不要照抄 NEWS 条目，去读实现它的 commit：

git log --oneline --grep=<issue-number>

或搜索该功能的名字。原因在于：NEWS 条目是写给已经熟悉产品的人扫描用的；而 commit message 与 diff 里才有用户真正需要的东西——菜单路径、命令名、工具栏按钮、功能的局限。用户问的第一个问题是「它在哪、什么时候不工作」，在条目里回答这个，页面才值得读。

仓库实证：blue-mistflower 页面中 "Fixed plot size" 条目给出Plots > Fixed Size...菜单路径、导出默认尺寸、600 DPI 上限等细节，均来自 NEWS.md 的 #4422 扩展信息。

7.2 措辞平实，不堆营销词

保持事实性。NEWS.md 与既往页面的行文风格是平实描述，比形容词堆叠读起来更好：

<li><strong>Active tab highlight:</strong> The active document tab now has a bold label and a blue overline. This can be turned off in <em>Tools &gt; Global Options &gt; General &gt; Basic</em>.</li>

7.3 固定结尾：Fixes 段

无论你是否在### Fixed下写了任何东西，页面永远以链接到发布说明的Fixes段收尾：

<div class="feature-section"> <h2>Fixes</h2> <p> For a full list of bug fixes in this release, see the <a href="https://www.rstudio.org/links/release_notes#rstudio-<CALENDAR_VERSION>.<PATCH>">release notes</a>. </p> </div>

每个版本的页面都原样携带这一段（仅锚点不同），它让 Step 4 的删减站得住脚：修复并没有对用户隐藏，它们一键可达，因此页面本身可以只承载值得公告的内容。种子占位符通常已含此段——保留它，并对照version/目录核对锚点，而不是假设发布分支时已更新。

因此，完成的页面按顺序为：New Features→ （如有弃用则）Deprecated→Fixes。

7.4 会反咬人的机械细节

• 不要动<head>：Content-Security-Policymeta 标签与whats-new-base.css链接由单元测试强制（见 Step 6）；
• 转义标记文本：菜单路径中的>写作>（如View > Split Editor），em 破折号用—，选项名与代码用<code>包裹；
• 不要添加未验证可访问的外链。桌面内容里的死链接比没有链接更糟——此页面随安装包出厂，无法不发布新版本就修正。

八、Step 6：验证

cd src/node/desktop && npm test

测试套件包含一个"whats-new content validation"用例（whats-new-utils.test.ts）：遍历whats-new/下每个版本目录，断言其index.html包含Content-Security-Policymeta 标签与whats-new-base.css样式表链接，缺一即失败。按桌面开发指南（见 src/node/desktop/CLAUDE.md）还应运行npm run lint与npm run typecheck；由于仅改动 HTML 资源，它们理应原样通过——任何失败都视为预先存在，应报告而非在此修复。

8.1 在运行中的 IDE 里查看页面

• 启动时强制弹出：设置环境变量RSTUDIO_SHOW_WHATS_NEW=1；
• 随时打开：Help > What's New菜单；
• 开发者构建在运行时从version/RELEASE读取发布名（resolveReleaseName()，whats-new-utils.ts），因此会显示进行中发布版本的内容文件夹——你可以在内容编写期间就预览它。打包构建则使用构建时烘入的发布名。

8.2 环境变量速查

必须在启动 RStudio之前于 shell 环境设置；写入.Renviron无效——What's New 检查在 Electron 进程中运行，先于 R 启动。

8.3 源码层的显示决策逻辑

启动时是否显示窗口由shouldShowWhatsNew()（session-launcher.ts）调用纯函数evaluateWhatsNewVisibility()（whats-new-utils.ts）决定，按最高优先级排序：

1. 内容必须存在（slug 合法且index.html可读），否则永不显示；
2. RSTUDIO_SHOW_WHATS_NEW强制显示，覆盖以下一切；
3. RSTUDIO_DISABLE_WHATS_NEW强制跳过；
4. show_whats_new用户偏好可禁用；
5. 仅发布构建自动显示；
6. 已看过的发布不再显示。

「已看过」状态由 whats-new-state.ts 中的WhatsNewState管理（electron-store 持久化seenReleases，按发布名而非补丁级别判重），窗口正常关闭时经onClose回调写入——崩溃或失去响应导致的异常关闭不会标记为已看过（whats-new-window.ts）。开发者构建不会持久化已看状态，避免压制最终打包发布版的弹窗。

九、Step 7：提交并打开 PR

• 提交信息：Populate What's New content for <CALENDAR_VERSION> (<Release Name>)
  • 例如：Populate What's New content for 2026.10 (Blue Mistflower)
• PR 正文：包含所选条目，并且——因为这是最不直观、审查者最可能二次质疑的决定——明确列出被排除的 NEWS 条目及排除理由；
• 里程碑：将version/RELEASE与现有里程碑对照（gh api repos/rstudio/rstudio/milestones --jq '.[].title'），匹配则设置，绝不新建里程碑。

无需 NEWS.md 条目：本页面本身就是发布说明内容，再为其添加条目会造成循环引用。也无需 GitHub issue 引用。

十、总结：一条可复用的发布流水线

将以上步骤压缩为一张速查表，供每个发布周期套用：

这条流水线的核心思想值得反复强调：发布说明写给所有接触产品的人，What's New 页面只写给一种受众——RStudio Desktop 的终端用户。所有筛选与撰写的判断，最终都回到这一个问题：用户打开这个窗口后，真正需要知道什么？

• 开发工具
• 后端