Hydra 发布流程深度指南release 工具与 GitHub Actions Trusted Publishing 驱动的包发布工作流【免费下载链接】hydraHydra is a framework for elegantly configuring complex applications项目地址: https://gitcode.com/GitHub_Trending/hyd/hydraHydra 的正式发布流程由本地发布工具tools/release/release.py与 GitHub Actions 工作流协同完成维护者在本地准备、校验版本与构建产物CI 则负责最终把包上传到 PyPI。本指南以 release 流程文档 为主线结合仓库内发布工具源码、发布配置与工作流定义完整讲解发布线release line、包集合package set、版本管理、准备阶段、本地校验以及 dev/rc/stable 各类发布的完整操作读者可按文中命令复现 Hydra 官方的发布节奏也可将此套本地校验 CI 发布模式迁移到自己的开源项目。发布架构总览本地准备、CI 上传Hydra 的 Python 包通过 GitHub Actions Trusted Publishing受信发布上传到 PyPI。整个流程的分工非常明确本地发布工具负责准备与校验版本设置、PyPI 状态比对、构建产物、冒烟安装检查GitHub Actions 负责最终上传Publish to PyPI工作流.github/workflows/publish.yml执行真实的 PyPI 上传动作。因此官方文档有一条硬性约束不要为 Hydra 发布在本地运行twine upload。本地最多只跑twine check校验产物上传一律交由 CI 完成。这样既可以利用 Trusted Publishing 的安全模型通过 OIDC 换取短期上传凭证无需在仓库中保存 PyPI token也让所有发布动作留痕在 GitHub Actions 运行记录中。本地发布工具本身就是一个 Hydra 应用在 tools/release/release.py 中通过hydra.main(config_pathconf, config_nameconfig)挂载配置入口是 tools/release/conf/config.yaml。其可执行动作定义在Action枚举中共六种动作枚举值用途checkAction.check比对本地版本与目标仓库PyPI已发布版本buildAction.build按策略构建发布产物bumpAction.bump在已发布包上递增到下一版本set_versionAction.set_version将选定包集合显式设置到指定版本validate_versionsAction.validate_versions校验选定包集合的本地版本与期望版本一致dev_releaseAction.dev_releasedev 发布的干跑或正式发布含提交、推送、派发工作流工具还定义了Repository枚举pypi/testpypi、BuildPolicy枚举unpublished/all以及Config数据类中的dry_run、build_dir、clean_build_dir、require_artifacts、publish、workflow_ref、only等配置项后续各小节会逐一展开。发布线Release lines与目标分支推导Hydra 的发布按发布线组织每条线有清晰的分工main分支承载当前未发布的活跃发布线x.y_branch例如1.4_branch承载某条已发布x.y线的候选版、稳定版、补丁版与 dev 版标签与 GitHub Release 使用包版本号如v1.4.0.dev1、v1.4.0rc1、v1.4.0、v1.4.1稳定文档按发布线做版本化例如version-1.3。发布自动化会根据发布线 目标版本推导目标分支活跃未发布线的 dev 发布通常基于main准备已发布线的 dev 发布基于该线的发布分支准备候选版、稳定版、补丁版一律基于发布分支如1.4_branch准备。分支覆盖branch override仅限非常规恢复场景或工作流测试且被严格限制为main或该发布线的x.y_branch。这一点在 .github/workflows/prepare-release.yml 的derive-release步骤中有完整实现脚本先校验release_line必须是x.y形式、release_date必须是YYYY-MM-DD形式再用正则严格匹配目标版本随后按已存在发布分支 → dev 用 main → 报错的顺序推导目标分支并拒绝任何超出main或x.y_branch的覆盖值且只有 dev 发布才允许覆盖到main。包集合Package sets与 only 过滤器发布工具是包集合感知package-set aware的set参数决定本次发布涉及哪些包。仓库中定义的五个集合及其对应配置set值包含内容配置文件hydra-core仅hydra-coretools/release/conf/set/hydra-core.yamlhydra-plugins捆绑的 Hydra 插件tools/release/conf/set/hydra-plugins.yamlhydra-full-releasehydra-core 捆绑插件tools/release/conf/set/hydra-full-release.yamlconfigen仅hydra-configentools/release/conf/set/configen.yamlallhydra-core 捆绑插件 hydra-configentools/release/conf/set/all.yaml默认的 Hydra 发布集合是hydra-full-release见 tools/release/conf/config.yaml 中defaults: - set: hydra-full-release。hydra-configen仍是受支持的发布目标但不在默认集合内。每个集合配置内部通过defaults引用packages/目录下的包配置如 tools/release/conf/packages/hydra.yaml、tools/release/conf/packages/hydra_optuna_sweeper.yaml、tools/release/conf/packages/configen.yaml包配置键名即only过滤器的取值。每个包配置声明了源码路径与版本文件位置例如 Optuna 插件指向plugins/${.name}与hydra_plugins/${.name}/__init__.py而hydra-configen采用version_type: SETUP版本从setup.py读取。在包集合内进一步收窄使用onlypackage_config_name[,package_config_name...]无需新增命名集合。例如只处理捆绑插件集合中的 Optuna 插件python tools/release/release.py \ actioncheck \ sethydra-plugins \ onlyhydra_optuna_sweeper \ repositorypypi在 shell 中传递多个逗号分隔的过滤器时务必加上引号让引号抵达 Hydra 后再解析例如onlyhydra_optuna_sweeper,hydra_ray_launcher。源码层面filter_packages()会校验only中的每个名字都属于当前选中集合遇到未知名称会直接抛错并列出可用包名。版本管理定义位置、设置命令与发布类型推导版本定义在哪里Hydra 核心版本定义在 hydra/init.py各插件版本定义在各自插件包的hydra_plugins/plugin/__init__.pyhydra-configen走setup.pyversion_type: SETUP。协调设置核心与插件版本对协调发布的 Hydra 版本应把核心与捆绑插件版本一起设置python tools/release/release.py \ actionset_version \ sethydra-full-release \ version1.4.0.dev2版本字符串必须使用PEP 440拼写如1.4.0.dev2、1.4.0rc1、1.4.0。set_version内部会先parse_version()校验合法性再对集合内每个包调用bump_version_in_file()通过正则定位__version__赋值行并改写为指定版本dry_run为真时只打印不落盘。发布后立即推进开发版本推进开发版本应紧跟发布之后进行而不是在准备下一次发布时。开发期间仓库检入的版本应始终标识下一个尚未发布的版本。例如发布1.4.0.dev2后应立刻把协调包版本设为1.4.0.dev3提交并推送该 bump再继续开发。这条纪律保证仓库中的版本永远不会指向已发布的状态。发布类型从版本号推导发布类型由目标版本字符串推导规则如下.devN版本 →dev 发布rcN版本 →发布候选release candidate最终x.y.0版本 → 该发布线的稳定发布最终x.y.zz 0版本 →补丁发布。在 .github/workflows/prepare-release.yml 的derive-release步骤中这一推导由正则与分支判断实现版本必须匹配x.y.z[rcN|.devN]且x.y必须与release_line一致否则直接报错退出。Prepare release发布前的维护者校验阶段Prepare release是发布前的维护者主导的校验阶段在真正发布之前完成一系列检查。它应当校验发布线由目标版本推导发布类型推导目标分支针对选定的包集合校验各包版本将选定包与 PyPI 上已发布版本比对运行 release 级别的检查。Release-grade 检查是什么Release-grade 检查 常规 CI 覆盖面 仅在发布时才运行的检查例如在安装全部选定兼容插件的情况下运行核心测试套件。这样可以把成本高、收益低的检查从日常 PR CI 中剔除但保留给发布决策使用。在 .github/workflows/prepare-release.yml 中release-validation任务在 Linux / macOS / Windows 三平台、Python 3.103.14 的矩阵上执行nox -s test_tools test_core test_jupyter_notebooks test_plugins test_plugins_vs_core -ts其中test_plugins_vs_core正是插件与核心同装的发布专属检查release-tool-check与artifact-build-check任务则在一次性的工作流 checkout 中完成版本设置、PyPI 比对与产物构建校验。重要边界Prepare release 不上传Prepare release绝不能向 PyPI 上传任何产物。当前工作流纯粹是校验步骤目标版本只应用于一次性的工作流 checkout 内部actionset_version不会污染仓库。生成 release-prep PR 属于准备阶段的既定目标但目前尚未自动化。对发布候选、稳定发布和补丁发布而言未来生成的 release-prep PR 将是发布的上线批准面PR 正文必须清楚说明合并该 PR 后会发生的动作一旦 release-prep PR 自动化落地合并该 PR 应触发向 PyPI 的发布且 PR 正文必须列出将要发布的包集合与精确版本。Dev 发布可以走更轻量的手动发布流程不要求 prepare PR。Prepare Release 工作流的手动输入Prepare Release工作流接收的输入包括release_line如1.4、target_version如1.4.0.dev2或1.4.0、package_set下拉选择默认hydra-full-release、可选的only过滤器、可选的target_branch_override仅恢复/测试用正常留空以及可选的release_date。本地检查与产物构建发布前比对目标仓库发布前先对比选定包与目标仓库的发布状态python tools/release/release.py \ actioncheck \ sethydra-full-release \ repositorypypi底层实现上get_package_info()先通过setup.py --version/setup.py --name读取本地包信息再调用get_metadata()请求https://pypi.org/pypi/name/jsontestpypi则请求test.pypi.org随后判断本地版本是否已在远端发布。check动作会逐个包打印✅ match本地与最新一致、✅ already published已发布但非最新或❌ unpublished标记。只构建尚未发布的产物只构建本地精确版本尚未发布到所选仓库的产物python tools/release/release.py \ actionbuild \ sethydra-full-release \ repositorypypi \ clean_build_dirtrue \ require_artifactstrue \ build_dir${PWD}/dist twine check ${PWD}/dist/*各参数的作用clean_build_dirtrue先清空构建目录prepare_build_dir()中若目录非空且未开启清理会直接抛错提示改用clean_build_dirtrue或空目录require_artifactstrue若按策略没有任何可发布产物被构建出来则报错退出避免静默发布空集build_dir${PWD}/dist把产物输出到当前目录下的dist/默认build_policyunpublished只构建本地版本未在远端发布的包is_publishable()返回真——已发布的版本会被跳过并打印说明。build_policyall只用于本地冒烟测试用于故意忽略仓库状态、强制构建全部选定包。每个包通过python -m build -o build_dir构建--sdist与--wheelbuild_targets默认值。twine check校验所有产物的元数据完整性。校验包集合已就绪确认选定的包集合已经在预期版本上就绪python tools/release/release.py \ actionvalidate_versions \ sethydra-full-release \ version1.4.0validate_versions对每个选定包读取本地版本并与version严格比对不一致即抛错validate_local_version()。PyPI 发布Dev 发布真实 dev 发布、候选版发布与稳定版发布都走PyPI 工作流.github/workflows/publish.yml。Dev 发布使用发布工具的dev_release动作。默认是干跑dry run它会展示选定包与版本的计划表、向 PyPI 检查目标版本是否已存在、在临时发布工作区中构建产物、运行twine check、无依赖冒烟安装 wheel并打印将会执行的精确发布工作流派发命令python tools/release/release.py \ actiondev_release \ sethydra-full-release \ version1.4.0.dev3干跑会打印一张包含包名 / 当前本地版本 / 目标版本 / PyPI 状态 / 最新 PyPI 版本的包计划表并禁止任何目标版本已发布fail_if_any_target_version_published()。源码中run_dev_release()在临时目录中copy_release_workspace()复制一份排除.git、dist等工作区再在其中执行版本设置、构建与冒烟检查从而保证本地仓库不被触碰。只干跑单个插件 dev 发布时收窄包集合即可python tools/release/release.py \ actiondev_release \ sethydra-plugins \ onlyhydra_optuna_sweeper \ version1.4.0.dev3真正发布 dev 版则追加publishtrue重跑。它要求工作区必须是干净的ensure_clean_worktree()脏树直接抛错当前提交必须匹配remote/workflow_refensure_publish_base_matches_ref()通过git ls-remote比对远端分支节点与本地 HEAD随后设置选定包版本如有变更则提交并推送最后通过gh workflow run publish.yml派发Publish to PyPIdispatch_publish_workflow()传入package_set、expected_version、publishtrue、only。python tools/release/release.py \ actiondev_release \ sethydra-full-release \ version1.4.0.dev3 \ publishtrue在正常发布节奏中选定包此刻已经处于该版本因为上一版本发布后立即 bump 过命令会跳过提交。该命令也可以在选定包版本不一致时代为设置、提交并推送目标版本但应视为恢复路径而非常规节奏。发布工作流成功后立即把选定包推进到下一个开发版本并提交、推送再恢复开发python tools/release/release.py \ actionset_version \ sethydra-full-release \ version1.4.0.dev4不要让你的开发分支报告一个已经发布过的版本。dev_release动作默认使用workflow_refmain。非常规场景例如从一条已发布线发布 dev 版可用workflow_refbranch-or-tag指定。需要特别注意的是dev_release干跑使用publishfalse不要设置dry_runtrue源码中会直接抛错二者不混用。发布候选、稳定发布与补丁发布这类发布的完整流程为为目标发布线与包集合运行Prepare release检出准备好的目标分支release branch用tools/release/release.py设置预期版本稳定发布还要用 towncrier 更新 NEWS.md提交并推送发布变更干跑手动运行Publish to PyPI工作流设置publishfalse选择包集合与可选的预期版本审阅工作流发布摘要确认将上传的精确产物准备好的发布状态合并后手动派发Publish to PyPI。预期未来由生成的 release-prep PR 取代此步骤——合并 PR 即触发发布版本与包集合以 PR 正文为准将 dev 与发布候选的 GitHub Release 标记为prerelease若被提示批准pypi-publish环境。Publish to PyPI工作流在提供预期版本时会校验选定包的版本actionvalidate_versions只构建本地版本比 PyPI 更新的产物actionbuildrequire_artifactstrue检查产物twine check、无依赖冒烟安装构建的 wheel最终通过 Trusted Publishing 发布。PyPI 工作流只能手动触发。手动运行默认publishfalse只有明确打算从该次手动运行真正发布时才设publishtrue。直接创建或编辑 GitHub Release不算发布批准也不会触发发布。工作流中的安全设计.github/workflows/publish.yml 将规划 / 构建 / 发布拆成三个独立 job使写权限只暴露给发布 jobrelease-plan只读校验输入并输出计划→build-artifacts在pypi-publish环境中构建、校验、写摘要→pypi-publish仅当计划启用发布时运行声明id-token: write以使用 Trusted Publishing。其中pypi-publish环境被配置为需要授权维护者审核与批准。发布摘要Release summary发布工作流会向 GitHub Actions 运行写入一份发布摘要包含目标仓库target repository发布模式publish modepublish或dry run包集合package set预期版本expected version若提供触发方式triggerrefcommit结果outcomedist/中产物的完整清单以产物名 | 大小表格列出。这份摘要就是面向维护者的这次发布到底会发布什么的标准答案。在 .github/workflows/publish.yml 的Write release summary步骤中dry run 模式会明确写出 Artifacts were built and checked only; no upload will run.而 publish 模式则写出 Artifacts will be uploaded to PyPI.配合产物表格一并写入 step summary。稳定发布后的文档更新每开启一条新的稳定发布线还需要同步更新网站更新 website/docs/intro.md 中指向最新稳定版的链接若创建了新发布分支用 Docusaurus 打一份新的版本化文档副本如version-1.4在 website/docusaurus.config.js 中更新指向新发布分支的指针。结语把本地校验 CI 发布固化进流程Hydra 的发布体系把可变状态操作版本改写、提交、推送、上传与校验动作严格分层本地工具负责一切可逆的准备与验证PyPI 上传被收口到受 Trusted Publishing 保护的手动工作流发布类型、目标分支、包集合都由配置与版本号自动推导防止人为误操作。这套设计既保证了每次发布的产物可审计、可复现也让 dev / rc / stable / patch 四种发布类型共享同一套代码路径——理解 tools/release/release.py、.github/workflows/prepare-release.yml 与 .github/workflows/publish.yml 三者的配合关系即可完整复现 Hydra 官方的发布节奏并将其中的先验证、后上传、上传只走 CI原则应用到自己的多包项目中。【免费下载链接】hydraHydra is a framework for elegantly configuring complex applications项目地址: https://gitcode.com/GitHub_Trending/hyd/hydra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考