Hydra 文档体系实战：用 towncrier 管理 NEWS.md，用 Docusaurus 构建官方站点

Hydra 文档体系实战：用 towncrier 管理 NEWS.md，用 Docusaurus 构建官方站点

【免费下载链接】hydraHydra is a framework for elegantly configuring complex applications项目地址: https://gitcode.com/GitHub_Trending/hyd/hydra

Hydra 仓库的文档基础设施由两部分组成：一是基于 towncrier 的 NEWS.md 变更日志流水线，贡献者只需提交小型 "news fragment" 文件，发布时自动聚合渲染；二是基于 Docusaurus 3 + pnpm 的官方文档站点，支持本地开发、静态构建与自动部署。读完本文，你将掌握 Hydra 中新闻片段的分类规则与放置约定、pnpm 工作区对依赖发布的稳定性策略，以及站点从pnpm start到 Netlify 部署的完整链路。

一、NEWS.md 由 towncrier 统一管理

Hydra 的 NEWS.md 并不由开发者手工维护，而是交给 towncrier 中定义了完整的片段规范：

• 文件名：以对应的 issue 或 PR 编号命名，扩展名为类别名，例如news/1234.bugfix；
• 放置位置：Hydra 核心变更放根目录 news/，插件变更放对应插件的news/目录，例如plugins/hydra_optuna_sweeper/news/1234.feature；
• 多类别变更：一个 PR 可以同时包含多个片段。比如既新增功能又弃用旧接口，就同时创建news/1234.feature和news/1234.api_change；如果一次变更涉及多个 issue 编号，可以为每个编号各建一个内容相同的片段，发布工具在渲染时会去重；
• 文风要求：片段应简洁、面向用户，使用句子式大小写（sentence case）、不超过 80 字符、祈使语气，且要能补全句子 "This change will ..."；片段文本中不需要写 issue/PR 编号，引用链接由发布工具自动追加。

当前仓库根目录的 news/ 目录就是这套机制的现场：目录下有大量形如2928.bugfix、3206.feature、3287.api_change的待发布片段，等待下一次 release 聚合进 NEWS.md。

1.1 towncrier 配置项解读

towncrier 的全部配置位于 pyproject.toml 的[tool.towncrier]段：

[tool.towncrier] package = "hydra" package_dir = "" filename = "NEWS.md" directory = "news/" title_format = "{version} ({project_date})" template = "news/_template.rst" issue_format = "#{issue}" start_string = "<!-- TOWNCRIER -->\n"

各字段的实际含义：

配置	值	作用
filename	NEWS.md	生成的变更日志目标文件
directory	news/	收集新闻片段的目录
title_format	{version} ({project_date})	每个版本标题的格式，即1.3.2 (2023-02-22)这样的版本号 (日期)形式
template	news/_template.rst	渲染所用的 Jinja2 模板，见下文
issue_format	#{issue}	片段后自动附加的 issue 链接格式
start_string	<!-- TOWNCRIER -->	NEWS.md 中的标记注释，towncrier 只在该标记之前插入新版本记录

同一配置段还通过[[tool.towncrier.type]]声明了受支持的片段类别，与 CONTRIBUTING.md 的约定一一对应：

扩展名	渲染标题	说明
feature	Features	新功能
api_change	API Change (Renames, deprecations and removals)	API 变更、重命名、弃用与移除
bugfix	Bug Fixes	缺陷修复
plugin	Plugins	插件相关变更
config	Configuration structure changes	配置结构变化
docs	Improved Documentation	文档改进
maintenance	Maintenance Changes	可维护性改进

1.2 渲染模板与最终效果

渲染逻辑由 news/_template.rst 控制。它是一个 Jinja2 模板：按 section 迭代，对每个类别输出### {{ definitions[category]['name'] }}小节，再把该类别下所有片段逐条以列表项输出；对非plugin/process类别，条目后会追加排序后的 issue 引用。若某类别为空，则输出 "No significant changes."。

打开 NEWS.md 可以看到渲染后的真实结果，例如1.3.2 (2023-02-22)版本下按 "Features"、"Maintenance Changes" 分节，每条变更都带有指向对应 issue 的链接——这正是issue_format与模板共同作用的产物。从源码结构看，仓库的tools/release/目录提供了 release 脚本与配套测试（tools/release/release.py、tools/release/test_release.py），发布流程会在打 tag 时驱动 towncrier 完成片段聚合与清理。

二、网站搭建：Docusaurus 3 + pnpm

Hydra 的官方文档站点位于 website/ 目录，基于 Docusaurus 3 构建（website/README.md 中说明的版本要求为 Node.js 24+ 与 Python 3.10+，Python 用于在站点命令执行前运行确定性的 Hydra Landscape 生成器）。

2.1 安装与本地开发

所有命令都在website目录下执行，通过 corepack 统一 pnpm 版本：

$ corepack pnpm install

安装完成后启动本地开发服务器：

$ corepack pnpm start

从 website/package.json 的 scripts 定义可以看到，start实际是：

"start": "node scripts/run-landscape-generator.mjs && docusaurus start --port 9134"

也就是说pnpm start会先运行 Landscape 数据生成脚本，再启动 Docusaurus 开发服务器（固定端口 9134）并打开浏览器窗口；大多数修改无需重启即可热更新生效。pnpm build同样会先生成 Landscape 数据，再把静态内容输出到build/目录，可交由任意静态托管服务部署；新增页面放入docs/后，可经http://localhost:9134/docs/page_name本地访问。部署则全自动完成：网站变更合入 main 分支后自动发布，构建环境由 netlify.toml 固定为NODE_VERSION = 24并使用--frozen-lockfile安装。

2.2 pnpm 工作区的依赖稳定性策略

文档中提到"pnpm 被配置为在依赖更新时避免解析最近 10 天内发布的 npm 包版本"，这一策略的具体实现就在 website/pnpm-workspace.yaml：

• minimumReleaseAge: 14400：即 14400 分钟（10 天），包版本发布未满 10 天不会被解析选中，以此规避刚发布即出现问题的包；
• minimumReleaseAgeExclude：为一批经过审查的包（如js-yaml@4.3.1、qs@6.15.2）豁免该限制；
• overrides：对 Babel、webpack、express、dompurify 等供应链关键包做版本锁定；
• allowBuilds/strictDepBuilds：禁用core-js、core-js-pure的构建脚本并启用严格依赖构建，收紧安装期执行面；
• patchedDependencies：将image-size@2.0.2指向patches/[e-mail]，以本地补丁修复该包的安全公告（同时在auditConfig.ignoreGhsas中忽略对应编号并注释说明原因）。

package.json还声明了"packageManager": "pnpm@11.21.0"与"engines": {"node": ">=24"}，配合 corepack 保证团队成员与 CI 使用同一 pnpm 版本。这些配置共同保证站点构建在可复现的依赖环境下进行。

2.3 版本化文档与跨版本源码链接

站点维护了多版本文档：website/versions.json 声明了1.3、1.2、1.1、1.0、0.11五个历史版本，对应的快照位于website/versioned_docs/，侧边栏分别定义在website/versioned_sidebars/下的各版本 JSON 中。

一个值得注意的细节是源码链接组件 website/src/components/GithubLink.jsx：GithubLink通过useActiveVersion()获取当前读者所在文档版本，再结合站点配置中的githubLinkVersionToBaseUrl映射，把to属性拼接为该版本对应的代码仓库路径。也就是说，当读者浏览 1.2 版本文档时，文中对源码的链接自动指向 1.2 分支的对应文件，而不是最新代码——本文关联文档 website/docs/development/documentation.md 中对NEWS.md、CONTRIBUTING.md的引用正是通过该组件渲染的。

三、小结：两条流水线如何协同

Hydra 的文档与发布流水线可以概括为：

1. 变更期：每次非平凡的 PR 附带一个或多个news/<编号>.<类别>片段，类别必须落在 towncrier 声明的七种扩展名之内；
2. 发布期：release 工具驱动 towncrier 按news/_template.rst模板将片段聚合渲染进 NEWS.md，版本标题与 issue 链接自动生成；
3. 展示期：Docusaurus 站点在pnpm start/pnpm build前先生成 Landscape 数据，站点变更合入 main 后经 Netlify（Node 24、frozen lockfile）自动部署，多版本文档与跨版本源码链接由versions.json与GithubLink组件共同支撑。

对贡献者而言，最重要的实操要点只有两条：在正确位置（核心或插件的news/目录）按正确类别创建片段文件，并保持片段文本简洁、面向用户；站点侧则只需在website目录内使用 corepack 管理的 pnpm 命令完成开发、构建与验证。

【免费下载链接】hydraHydra is a framework for elegantly configuring complex applications项目地址: https://gitcode.com/GitHub_Trending/hyd/hydra