企业官网建设流程全解析

• 医疗健康
• 后端

导读

本文围绕 OpenEMR 发布自动化体系中一份特殊的"黄金基准"文件——post-ghsa 场景的期望输出，系统剖析 8.2.0 版本发布说明（CHANGELOG）的自动化生成全链路：从 ChangelogGenerator 的 PR 分类、噪音过滤、区域分组，到 GitHub Security Advisory（GHSA）如何通过Patched versions约定被匹配并渲染为### Security Fixes安全公告区块，再到 fixture 回归测试 如何把一次真实的发布回放锁定为可断言、可复现的基准。读完本文，你将掌握 OpenEMR 发布说明的完整渲染规则、发布后安全公告补丁（release-amendment）的运作机制，以及如何通过 fixture 捕获工具在仓库中复现与更新这一基准。

一、一份 1424 行的"期望输出"文件在发布自动化中的角色

tests/Tests/Isolated/Release/fixtures/8_2_0/post-ghsa/expected.md并不是普通的发布说明，它是 OpenEMR 发布自动化体系中回归测试的锁定基准。该目录还包含三个兄弟文件：

• commits.json ——v8_0_0...v8_2_0提交范围内的全部 SHA 列表；
• prs.json —— 约 650 个 PR 的真实对象（编号、标题、标签、URL、作者），约 1.7 万行；
• release-time/expected.md —— 同一发布在release-prep 合并时刻（安全公告仍为草稿）渲染出的对照输出，该版本没有 Security 区块。

两个expected.md只有一行之差，却精确刻画了发布流程中两个关键时间点：发布准备期（GHSAs 未发布，无安全公告）与发布后补丁期（GHSAs 已发布，生成### Security Fixes）。这正是"post-ghsa"命名的由来——ChangelogGeneratorFixtureTest.php 中的两个测试方法分别回放这两个场景并断言输出与基准逐字节一致。

从源码结构看，这份 fixture 的价值在于：它用一次真实的 8.2.0 发布（约 650 个 PR、一个真实 GHSA）端到端验证生成器的"过滤器 + 分类器 + 区域分组 + 安全公告匹配"组合逻辑，弥补了单测只针对合成 PR 形状、无法捕捉跨模块交互的盲区（见 ChangelogGeneratorFixtureTest.php 的测试注释）。

二、8.2.0 发布说明的结构解剖：从输出反推渲染规则

expected.md的渲染结果本身就是格式规范的最佳说明书。其顶层结构为：

## 8.2.0 - 2026-07-08 ### Security Fixes - [High] OpenEMR FaxSMS module: insecure staging of decrypted patient documents in webroot (CWE-552/CWE-200) (GHSA-vv5j-6gjw-ffx9) ### Fixed - accept bare image tag in docker-compose mutator (#12283) ... #### <区域标签> ... ### Added ### Changed

对照 ChangelogGenerator.php 的常量定义，可还原出以下核心渲染规则：

8.2.0 的完整 changelog 共 1424 行，Fixed区块内可见 30+ 个####区域子分组，如ASTP/ONC Certification、Authentication、Backend Modernization Project、CCDA Service、Calendar、Database Layer、Database Migrations & Schema Changes、DevOps、Hardening、Security、REST API、billing & payments、communications、docker等。区域标签完全来自 GitHub 上 PR 的实际 label，这也是SKIP_LABELS（如backport、Stale、Status: Needs Review等流程性标签）被排除、不作为分组依据的原因。

2.1 标题中的类型前缀如何被消费

从 prs.json 可以看到真实输入形态：chore: change master dev version to 8.0.1、fix: checks broken in previous merge、feat: ...。categorize()首先用CC_PATTERN提取类型与正文，然后根据CATEGORY_MAP归类；不匹配正则的标题（如直接以动词开头的accept bare image tag ...）落入Changed或保持fix类的原语义——实际上从输出看，accept bare image tag in docker-compose mutator被归入了### Fixed，因为它的标题以动词开头但属于"修复"，这正是"无前缀落入 Changed"之外的标签驱动分组的体现。从源码结构看，区域标签对最终分组的贡献高于标题前缀。

三、噪音过滤：哪些 PR 不会出现在发布说明中

expected.md中没有出现在prs.json里的 PR 数量远多于保留的。过滤逻辑集中在filterNoise()/isNoise()（ChangelogGenerator.php），共四类：

1. 发布机器人：作者为openemr-release-bot[bot]的 PR 全部丢弃（版本号提升、标签创建、同步 PR 等纯发布机制，对用户不可见）；
2. 测试占位：标题含[TEST]的 PR 丢弃；
3. 手工 release-cut：标题匹配/^chore(?:\([^)]*\))?:\s*release\s+v?\d/i的 PR 丢弃——注意该正则要求必须带版本号，避免误伤chore(docs): release notes update这类把 "release" 当普通英文词使用的标题；
4. Dependabot 噪音：仅针对dependabot[bot]作者，两个子规则：
   • isNoOpVersionBump()：标题中from X to Y且 X == Y（版本未变的重复 pin）丢弃；
   • isDockerBump()：标题含in /docker/或in /ci/路径信号，或命中DEPENDABOT_DOCKER_GROUPS（mariadb、redis、mysql、selenium等 docker-compose 分组名）的丢弃。

值得注意的是两条有意不应用的规则（源码注释明确记录，2026-07-15 放宽）：标题含 "backport" 的 PR保留——因为 rel 分支上的 backport 恰恰是该版本实际发布的修复（例如 8.2.0 中的server-status polling now terminates reliably (rel-820 backport for 8.2.0)#12827 与skip audit logging on the status poll endpoint#12832，正是它们被早期严格过滤器吞掉、导致 8.2.0 首个 changelog 缺失用户可见修复后才放宽）；fix(release):/ci(release-prep):等发布机制 PR 也保留，供开发者与发布工程师在 changelog 中看到发布机制的演进。

3.1 Composer/npm 依赖更新不受影响

isDockerBump与isNoOpVersionBump仅作用于 Docker 镜像与 CI 基础设施；composer/npm 依赖提升（如bump predis/predis from 3.3.0 to 3.4.0、bump twig/twig from 3.22.2 to 3.23.0）会作为真实用户可见变更进入### Dependencies区块——这就是 8.2.0 changelog 中PHP分组下大量bump ...条目的来源。

四、GHSA 安全公告匹配：Patched versions精确匹配约定

post-ghsa/expected.md与release-time/expected.md的唯一差异，也是全文最重要的内容——顶部新增的 Security Fixes 区块：

### Security Fixes - [High] OpenEMR FaxSMS module: insecure staging of decrypted patient documents in webroot (CWE-552/CWE-200) (GHSA-vv5j-6gjw-ffx9)

配套的 advisories.json 展示了其数据来源：GHSA 的ghsa_id、severity: "high"、summary、html_url，以及关键的vulnerabilities[0].patched_versions: "8.2.0"。匹配逻辑分两条路径（advisoryMatchesRange()）：

1. 主路径（实际生效）：patched_versions字段与目标版本字符串严格相等（===）。OpenEMR 的 GHSA 发布流程不填写自由格式的 References 字段，因此这条是唯一的现实匹配信号；
2. 回退路径：解析 References 中的 URL，若包含本发布范围内 40 位 commit SHA 或 PR 编号则匹配。

因此 RELEASE_PROCESS.md 中确立了一条硬性约定：发布 GHSA 时，Patched versions必须填写精确版本串（如8.2.0），不得使用范围或逗号分隔列表——匹配器是严格精确匹配。多个匹配公告按严重级别排序（critical → high → medium → low），同级按 summary 字典序（matchAdvisories()）。

4.1 渲染层面的安全加固

formatAdvisories()与formatPrLine()对输出做了两层防护：escapeMarkdown()转义[与]，防止 PR 标题、区域标签、公告摘要注入 Markdown 链接语法；sanitizeGitHubUrl()只允许https://github.com/openemr/前缀的 URL，其余一律替换为中性占位链接，杜绝"越域"链接被带进发布说明。

五、fixture 回归测试：如何把一次真实发布锁进 CI

ChangelogGeneratorFixtureTest.php 是这套体系的验证中枢，其设计要点：

• 双场景回放：testRegeneratesEightPointTwoZeroAtReleaseTime()与testRegeneratesEightPointTwoZeroPostGhsaAmendment()分别加载release-time/与post-ghsa/的advisories.json+expected.md；
• FakeGitHubApi 注入：用commits.json、prs.json、advisories.json构造假 API，不触网、可离线运行；
• 冻结时钟：FrozenClock锁定2026-07-08T00:00:00+0000，保证标题日期与真实发布一致且输出确定；
• 基准选择：base 用v8_0_0（上一个真正发布的版本，2026-02-11 上线）而非v8_1_0（已 cut 但从未发布），与ChangelogMutator通过BranchVersionResolver推导prev_release的行为保持一致（见测试头部注释）；
• includeGhsa: true：post-ghsa 场景显式开启 GHSA 匹配，验证 Security Fixes 区块渲染。

5.1 更新基准的标准流程

当生成器的过滤、分类、区块顺序或公告渲染有意发生变化时，重新生成基准的流程（测试注释与 capture-changelog-fixture.php 均有说明）：

# 1. 从真实 GitHub API 重新捕获该版本的输入状态 php tools/release/bin/capture-changelog-fixture.php \ --base=v8_0_0 --head=v8_2_0 --target-version=8.2.0 \ --fixture-dir=tests/Tests/Isolated/Release/fixtures/8_2_0 # 2. 以 UPDATE_FIXTURE=1 模式重跑测试，将当前输出写回 expected.md UPDATE_FIXTURE=1 php <phpunit> --filter ChangelogGeneratorFixtureTest # 3. 审查 diff 后连同代码变更一并提交

捕获工具会按约定过滤公告：release-time/advisories.json写空列表（模拟发布准备期草稿状态），post-ghsa/advisories.json只保留patched_versions精确等于目标版本或引用落在范围内的公告，从而保证上游后续发布无关 GHSA 不会污染 fixture 的稳定性。

六、post-ghsa 场景背后的业务流：发布后安全公告补丁

expected.md的生成不是孤立的，它对应 RELEASE_PROCESS.md 中"Quick action 4：发布后 GHSA 补丁"：

1. 在openemr/openemr发布每个 GHSA，Patched versions填精确版本串（如8.2.0）；
2. 手动触发 release-amendment.yml（workflow_dispatch），选择刚发布的version+rel_branch；
3. 工作流对打标签后的状态重跑ChangelogMutator+CompatibilityMutator，在 rel 分支与 master 各开一个release-amendment/<version>-<rel-branch>/release-amendment/<version>-master变更 PR；
4. 同一运行内用gh release edit --notes-file更新 GitHub Release 正文、用gh release upload --clobber更新changelog.md附件，使CHANGELOG.md、Release 正文、附件、变更 PR四个面收敛。

该流程刻意设计为幂等：ChangelogMutator每次运行时整体替换目标## [X.Y.Z]区块，无新 GHSA 时重新派发不会产生 diff（peter-evans 跳过无变化的 PR 更新，Release 编辑在区块未变时为空操作）。文档同时给出明确警告：手工编辑的措辞在重跑时会被抹掉——生成器的输出才是事实来源（RELEASE_PROCESS.md）。

从 release-automation-plan.md 看，release-amendment 只是五个协调工作流之一，其余为 branch-cut、patch-prep、release-prep（指挥者）与 release-mechanism-smoketest，共同构成"从 cut 到 ship 再到 post-ship"的完整生命周期闭环。

七、阅读 8.2.0 发布说明的实用视角

通过源码与测试理解了生成规则后，再读这份 1424 行 fixture 就有章可循：

• ### Fixed区块中的子分组反映功能面：Security分组下是 CSRF、SQL 参数化、XSS 转义、路径穿越校验等 60+ 项加固（如parameterize SQL in patient.inc.php and harden column name escaping#11214、harden escape_sql_column_name() with backtick-quoting#11280、protect bin/ directory from web access#10895），Backend Modernization Project分组记录 Doctrine/DBAL 引入（#9980）、前端控制器（#9943）、DI 容器（#11001）等现代化里程碑；
• ### Added与### Changed中的发布机制条目是留给发布工程师的信号：branch-cut automation — opens rel-side + master-side PRs on cut#12696、patch-prep automation (workstream 6)#12697、byte-identical canary#12580 等，标注了发布机制本身在 8.2.0 周期的演进；
• 跨发布对比的起点：当前仓库 version.php 已演进到8.5.0-dev、v_database = 546，后续版本的 changelog 基准遵循完全相同的规则与流程，release-time/与post-ghsa/的双场景对比方式依然适用。

八、复现与验证指引

想要亲自验证这套机制，可在当前仓库中：

1. 阅读生成器全量实现 tools/release/src/ChangelogGenerator.php（609 行），重点看filterNoise、categorize、matchAdvisories、formatPrs四个方法；
2. 对照单测 ChangelogGeneratorTest.php 中针对每条过滤分支的合成用例（如 release-bot 丢弃、[TEST]丢弃、backport 保留、docker bump 丢弃）；
3. 运行 fixture 回归测试ChangelogGeneratorFixtureTest，观察 8.2.0 两个场景是否与基准一致；
4. 查看发布流程文档 docs/RELEASE_PROCESS.md 的 Conductor PR 章节与 release-amendment 工作流，理解expected.md在"发布 → 打标签 → GHSA 发布 → 补丁派发"链条中的位置。

这套"真实数据回放 + 冻结时钟 + 黄金基准"的测试模式，是发布说明自动化可靠性的基石——任何分类规则、过滤策略或公告渲染的变化，都必须先通过 8.2.0 这次真实发布的回放检验，才能进入下一个版本的 changelog。

• 医疗健康
• 后端