Ultraplot项目发布工作流问题分析与解决方案

Ultraplot项目发布工作流问题分析与解决方案

问题背景

在Ultraplot项目的持续集成/持续部署(CI/CD)流程中，开发团队遇到了发布工作流(publish workflow)无法正常执行的问题。这个问题最初表现为GitHub Actions工作流在发布环节被跳过，随后又发现了版本号计算异常的情况。

技术分析

初始问题定位

1. 工作流跳过问题：当开发人员手动推送标签(tag)时，GitHub Actions的发布工作流会被跳过。这是预期行为，因为GitHub的发布机制设计如此。正确的做法是通过GitHub UI界面创建正式的Release，这样才能正确触发发布流程。

2. 版本号计算问题：更深入的技术问题出现在setuptools_scm工具的版本号计算上。该工具错误地将下一个版本计算为1.0.4，而实际上应该是1.0.5。这表明项目的版本控制配置可能存在问题。

根本原因

经过分析，问题的核心在于：

1. 发布触发机制误解：团队成员对GitHub的发布触发机制理解不够深入，错误地认为直接推送标签就能触发发布流程。

2. 版本控制工具配置：setuptools_scm作为Python项目的版本管理工具，其配置可能没有正确反映项目的实际版本历史，导致版本号计算错误。

解决方案

1. 正确的发布流程：

   • 通过GitHub UI界面创建正式的Release
   • 避免直接推送标签来触发发布
   • 确保发布前的所有测试和验证流程都已完成

2. 版本控制修复：

   • 检查并修正setuptools_scm的配置
   • 确保项目的版本历史记录完整准确
   • 必要时可以手动指定版本号作为临时解决方案

3. 工作流优化：

   • 在GitHub Actions工作流中添加版本号验证步骤
   • 设置更明确的触发条件
   • 增加错误处理和日志记录

经验总结

1. CI/CD流程理解：团队成员需要充分理解所用平台的发布机制，特别是像GitHub这样的平台有其特定的工作方式。

2. 工具链熟悉度：像setuptools_scm这样的工具虽然强大，但需要正确配置和理解其工作原理。

3. 问题排查方法：从表面现象(工作流跳过)到深层原因(版本号计算错误)的排查过程，展示了系统化问题解决的重要性。

最终效果

经过上述调整和修复后，Ultraplot项目的发布工作流已恢复正常运行，能够正确计算版本号并通过GitHub Actions完成向PyPI的发布流程。最新版本1.0.5已成功发布到PyPI仓库。