跳转至

MinerU Alpha 发布设计

目标

从不可变的 Git 标签发布 PEP 440 Alpha 版本(例如 4.0.0a1)到现有的 mineru PyPI 项目,且不改变当前稳定版或 mineru-next-dev 发布流程。

发布契约

  • Alpha 发布使用名为 vX.Y.ZaN 的附注标签,例如 v4.0.0a1。
  • 被标记的提交必须包含在远程 next 分支中。
  • 被标记提交处的 mineru/version.py 必须包含与标签去掉前导 v 后相同的版本。
  • 工作流会检出并构建被标记的提交,而不是最新的移动分支头。
  • 构建出的 wheel 元数据必须包含预期的项目名称和版本。
  • 成功上传到 PyPI 后,会创建一个标记为预发布的 GitHub Release。

工作流结构

独立的 .github/workflows/alpha-release.yml 工作流仅由匹配宽泛 Alpha 标签 glob 的标签触发。随后,一个 Python 验证辅助程序会强制要求精确的规范标签格式。

构建作业:

  1. 以完整历史检出被标记的提交;
  2. 获取 origin/next 并验证被标记的提交是其祖先;
  3. 验证标签和 mineru/version.py;
  4. 构建 wheel 并运行包元数据检查;
  5. 在干净的虚拟环境中无依赖安装该 wheel,并验证其已安装发行版版本;
  6. 将经过验证的 wheel 作为工作流工件上传。

发布作业下载恰好该工件,并使用 Twine 发布它,使用与稳定版发布工作流相同的 PyPI API token 认证。它使用 Python 3.12,并显式安装 packaging>=24.2,以便 Twine 能够验证在 Core Metadata 2.4 中输出的 PEP 639 许可证字段。该作业在上传前再次运行严格的元数据检查。token 通过 Twine 的 TWINE_PASSWORD 环境变量从 PYPI_TOKEN GitHub 机密读取。该作业仍与受保护的 pypi GitHub 环境关联。

最终作业创建一个 GitHub 预发布,并附加同一个 wheel。它仅在 PyPI 发布作业成功后运行。

安全与失败行为

  • 在可行的情况下,第三方 actions 固定到不可变的提交 SHA。
  • 默认工作流权限为只读;写权限仅限定于需要它们的作业。
  • PyPI 认证使用现有的 PYPI_TOKEN GitHub 机密。该 token 应限定到 mineru 项目,并根据发布凭据策略轮换。
  • 并发限定到标签,因此同一标签的重复运行不能并发发布。
  • 现有 PyPI 版本不会被静默跳过。由于已发布的文件不可变,重复上传会明显失败。
  • 验证、构建或冒烟测试失败会在发布作业之前停止。

操作者流程

  1. 在 next 上更新 mineru/version.py,例如更新为 4.0.0a1。
  2. 提交版本更改,并让正常 CI 通过。
  3. 创建并推送附注标签 v4.0.0a1。
  4. 确保仓库或 pypi 环境提供 PYPI_TOKEN 机密。
  5. 如有需要,批准受保护的 pypi 环境部署。

工作流实现可以在本地测试,而无需创建或推送标签。仅添加工作流不会发布任何内容。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 mi/MinerU