Foundry 的 Changelog 碎片与版本发布自动化：`.changelog` 工作流完全解析

Foundry 的 Changelog 碎片与版本发布自动化.changelog工作流完全解析【免费下载链接】foundryFoundry is a blazing fast, portable and modular toolkit for Ethereum application development written in Rust.项目地址: https://gitcode.com/GitHub_Trending/fo/foundry本文深入解析 Foundry 仓库中.changelog/README.md所定义的 changelog 碎片fragment与版本发布自动化机制从固定版本的changelogsCLI、workspace.package版本契约、start/advance/promote三种 RC 过渡操作到 Pull Request 碎片格式与确定性校验规则并结合仓库内的验证脚本与 CI 工作流源码说明这套系统如何在forge、cast、anvil、chisel等 39 个 workspace 包之间统一推进版本。读完本文你将掌握 Foundry 的 changelog 条目写法、本地检查命令以及从碎片到vX.Y.Z稳定标签的完整发布链路。一、总览碎片驱动的 changelog 体系Foundry 采用碎片fragment驱动的 changelog 模式每个 Pull Request 在 .changelog 目录下新增或修改一个*.md文件文件头部是 YAML 风格的 frontmatter声明涉及哪些包以及对应的版本递增级别发布时由固定的changelogsCLI 汇总这些碎片生成统一的根 changelog 与版本号。这一设计把发布说明的责任下沉到每个 PR 作者身上并通过 PR 校验工作流 与 校验脚本 做确定性检查而不是依赖人工整理或 AI 建议。.changelog目录里保存了数百个这样的碎片例如 .changelog/forge-lsp.md、.changelog/anvil-arbitrum-l1-block-number.md它们是每次发布说明的原始素材。二、固定版本的 changelogs CLI2.1 为什么必须固定版本Foundry 使用第三方工具tempoxyz/changelogs并固定到具体 commit而不是跟随最新版以保证本地操作、CI 校验与发布行为完全一致。安装命令cargo install \ --git https://github.com/tempoxyz/changelogs \ --rev 74f07b39c7c85773575e32472dfd5298ec6baaf4 \ --locked规则非常明确所有 CLI 命令与 GitHub Action 引用必须使用该精确修订号禁止使用 check action 内置的 AI 安装器——它不固定 CLI 版本会引入不确定性。这一约束在 stable-version-pr.yml 中体现为环境变量CHANGELOGS_REV: 74f07b39c7c85773575e32472dfd5298ec6baaf4CI 安装时直接引用该值cargo install \ --git https://github.com/tempoxyz/changelogs \ --rev $CHANGELOGS_REV \ --locked \ --root $RUNNER_TEMP/changelogs2.2 本地三件套doctor / status / version安装后可以本地运行以下命令检查仓库 changelog 状态changelogs doctor changelogs status changelogs version --dry-runchangelogs doctor体检配置与碎片健康度changelogs status查看当前碎片与版本计划状态changelogs version --dry-run只读地预演下一个版本号不产生任何写入适合在提交发布 PR 前确认版本走向。三、版本契约Version Contract版本契约定义了 workspace 清单、稳定标签与 nightly 版本之间必须严格满足的关系workspace manifest 记录下一个发布候选RC版本版本号集中维护在根 Cargo.toml 的[workspace.package]段。以当前仓库为例[workspace.package] version 1.8.2 edition 2024 rust-version 1.89清单已领先最新稳定标签时发布准备直接使用该候选不再二次递增。文档举例采用时1.7.2跟在v1.7.1之后直接映射到v1.7.2。从源码看prepare-stable-release.py 通过正则WORKSPACE_VERSION直接改写[workspace.package]的version字段且只替换一次count1。Nightly 使用候选版本号使1.7.2-nightly在 SemVer 语义上恒大于稳定版1.7.1当稳定版前进时候选版本必须同步前进否则 nightly 会被追平。稳定标签vX.Y.Z必须指向 workspace 版本恰为X.Y.Z的提交——版本号与标签一一对应不允许漂移。生成的CHANGELOG.md历史从采用该机制时开始历史版本不回填。仓库根目录的 CHANGELOG.md 目前为空文件正是这一契约的直接体现历史不回溯内容只从碎片机制启用后的发布开始累积。四、发布自动化规范的版本与 RC 过渡4.1 只接受规范版本形式发布自动化只接受两类输入类型形式说明稳定版本X.Y.Z/vX.Y.Z不带前导零直接发布严格 RCX.Y.Z-rcN/vX.Y.Z-rcNN 1必须从rc1开始连续遗留的预发布形式如alpha、beta、-next等被排除在过渡状态之外。手动触发时操作者必须显式确认 source 与 target 标签防止误操作。4.2 三种 RC 操作操作作用碎片要求start把已检入的稳定候选变成rc1需要并消耗碎片advance把最新的同核心 RC 推进到下一个 RC需要并消耗碎片promote去掉 RC 后缀转正为稳定版必须零碎片CHANGELOG.md保持不变对源 RC 标签还有严格的前提校验标签必须存在、必须是同核心最新 RC、必须从rc1形成连续序列、并且必须是发布提交的祖先。4.3 源码级支撑prepare-stable-release.py 是这套过渡的核心实现其中VERSION re.compile(r(\d)\.(\d)\.(\d)(?:-rc([1-9]\d*))?)、TAG re.compile(rv(\d)\.(\d)\.(\d)(?:-rc([1-9]\d*))?)强制规范版本与标签格式rc数字必须以非零开头parse_version会拒绝任何非规范写法例如1.8.2-rc0或v1.8.2-rc01strict_tags只收集规范 tag从git tag输出中筛选出可参与发布计算的标签集合run_preserving_lockfile在执行版本命令后恢复Cargo.lock原内容避免发布准备过程意外改动依赖锁文件。OPERATIONS {stable, start, advance, promote}中除三种 RC 操作外还有stable对应直接准备稳定发布不经过 RC。从仓库看workspace 当前版本为1.8.2说明候选版本推进到该值后等待稳定化流程处理。五、根 Changelog 格式与发布范围5.1 Root 格式配置.changelog/config.toml 内容如下ecosystem rust dependent_bump none ignore [] [changelog] format rootformat root根 changelog 格式——所有被发现的包共享一个统一版本号而不是每个 crate 各有一套版本dependent_bump none依赖方不因被依赖方变化而自动递增ignore []默认不忽略任何碎片。5.2 发布计划中的包范围文档给出了一份关键数据来自固定修订版下的一次只读 dry run共发现37 个发布计划包forge-sol-macro-gen与foundry-test-utils被排除原因是它们设置了publish false全部39 个 workspace 包继承根版本。也就是说39 个包在清单层面共享根版本但其中 2 个不参与对外发布因此实际进入发布计划的只有 37 个。这与校验脚本 validate_changelog.py 中的逻辑一致package_names通过cargo metadata读取 workspace 成员并过滤掉package.get(publish) []的包只有可发布包才允许出现在碎片的 frontmatter 中。5.3 不发布到 registryFoundry不会把 workspace crate 发布到 crates.io 之类的注册表。因此自动化流程中不得调用changelogs publish不得使用根tempoxyz/changelogscomposite actionFoundry 自己的自动化负责版本 PR 与标签的创建。这解释了为什么发布产物是 GitHub Release 上的二进制归档与 Docker 镜像见 release.yml 中forge cast anvil chisel solar五件套的构建矩阵而非注册表 crate。六、Pull Request 碎片规范6.1 必须添加碎片除非豁免Pull Request 必须新增或更新.changelog/*.md条目除非维护者打了现有的L-ignore标签。豁免适用于不应出现在发布说明中的改动例如纯 CI 或仓库维护类变更。6.2 条目格式每个碎片把一个或多个 workspace 包名映射到patch、minor或major并包含非空的发布说明--- forge: minor cast: patch --- Added a Forge feature and fixed the related Cast behavior.仓库中真实的碎片示例.changelog/forge-lsp.md--- forge: minor forge-lint: patch --- Added forge lsp to start Solars Solidity language server without installing the standalone solar executable. The server follows Forges normal CLI flow, and its default flycheck uses the running Forge executable while keeping protocol output isolated on stdout. ...6.3 确定性校验规则PR 校验是确定性的与任何 AI 建议无关。校验脚本 validate_changelog.py 会拒绝frontmatter 必须以独立的---行开头和结尾包映射不能为空包名必须是真实存在的 workspace 包未知包直接报错递增级别只能是major、minor、patch三者之一不允许重复的 frontmatter 键发布说明不能为空只删除条目不算满足要求例外frontmatter 中允许出现commit键不计入包计数这是供工具使用的特殊键。七、CI 工作流全景整个 changelog → 版本 → 发布的链路由以下工作流串联changelog.ymlPR 校验 引导pull_request事件触发validatejob从 base 分支检出可信校验器sparse checkout 只取validate_changelog.py再检出 PR 代码运行python3 validate_changelog.py --root pull-request --base $BASE_SHA --head $HEAD_SHA传入--exempt时跳过条目要求pull_request_target事件触发guidancejob当 PR 缺少碎片且未豁免时在 PR 上发布需要 changelog 条目的引导评论并可附上 AI 生成的建议性条目评论明确声明由确定性检查决定条目是否有效而非本建议。这与文档不要使用内置 AI 安装器的精神一致——AI 只做辅助不参与裁决。stable-version-pr.yml版本 PR监听 master 分支上.changelog/*.md、Cargo.toml、Cargo.lock、CHANGELOG.md等文件的 push支持手动触发start/advance/promote并要求操作者填写确切的source_tag与target_tag调用prepare-stable-release.py生成release/version分支的 PRPR 正文携带结构化元数据Operation / Source tag / Target version / Changelog fragments / Workspace packages该 PR 自动打上L-ignore标签——因为它本身是版本管理改动不需要碎片。tag-stable-release.yml校验并打标签校验release/versionPR 只能由发布 App 创建、标题与元数据严格匹配、promote操作必须对应零碎片、PR 必须基于最新的 master合并后用create-tag.js在精确的合并树 commit上创建vX.Y.Z或vX.Y.Z-rcN标签。release.yml构建发布通过 tag push 触发稳定/RC 发布通过 cron 或手动触发 nightly用 .github/changelog.json 驱动的mikepenz/release-changelog-builder-action从 PR 与标签生成 GitHub Release 说明其中按C-anvil/T-feature/T-bug等标签归类为 Breaking changes、Anvil Features、Cast Fixes 等章节生成并签名归档、校验和、SBOMSPDX、cosign 签名与 attestation稳定版发布保持 draft等待受保护的 finalize 流程nightly 由publish-nightlyjob 自动发布。finalize-release.yml收尾转正必须从master分支手动触发输入要 finalize 的 tag调用 finalize-release.py 完成最后的发布动作。八、发布说明的归类changelog.json在 GitHub Release 说明生成阶段.github/changelog.json 定义了 PR 到章节的映射规则与碎片系统互补标签T-likely-breaking→## Breaking changesC-anvilT-feature→## Anvil FeaturesexhaustiveC-anvilT-bug→## Anvil FixesC-cast/C-chisel/C-forge同理分为 Features 与 FixesT-perf→## Performance improvements未归类的进入## Otherignore_labels为L-ignore。每条 PR 以- ${{TITLE}} (#${{NUMBER}}) by ${{AUTHOR}}的模板呈现最终模板为${{CHANGELOG}}\n## Other\n\n${{UNCATEGORIZED}}\n## Full Changelog:\n ${{RELEASE_DIFF}}。九、实践要点与注意事项写碎片时确认包名与 Cargo.toml 的 workspace 成员一致只能写forge、cast、anvil、chisel、solar、forge-lint等真实包名publish false的包如forge-sol-macro-gen、foundry-test-utils不能出现在 frontmatter 中。本地自检提交 PR 前运行changelogs doctor、changelogs status、changelogs version --dry-run确保碎片合法、版本计划符合预期。CI 之外不要手动发布仓库不向注册表发布 crate所有标签与版本 PR 都由 Foundry 自有自动化完成人工只负责触发start/advance/promote并确认 source/target 标签。AI 建议仅供参考即使 CI 评论提供了 AI 生成的条目模板最终合法性仍由 validate_changelog.py 的确定性规则裁决。豁免条件只有维护者打上L-ignore标签才可免除碎片且该豁免仅适用于不该进发布说明的改动如纯 CI 调整。这套体系把版本号从哪来、发布说明写什么、标签何时打全部固化为可校验的机器规则既保证了1.8.2-nightly 1.8.1的 SemVer 单调性也让每个 PR 的变更以碎片形式沉淀为下一次发布的素材是大型 Rust workspace 项目做自动化发布的完整参考实现。【免费下载链接】foundryFoundry is a blazing fast, portable and modular toolkit for Ethereum application development written in Rust.项目地址: https://gitcode.com/GitHub_Trending/fo/foundry创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考