如何在Monorepo中自动生成Python包版本？相关最佳实践探讨

在单包仓库里用约定式提交生成语义化版本很直接，但在多产品独立版本的Monorepo场景下，需要一套适配包隔离、自动版本计算的规范和工具链，以下是可落地的最佳实践：

一、分支命名语义 #

统一分支命名规则，明确分支用途与关联产品，避免混乱：

• 主分支：main/master，存储所有产品的正式发布版本，仅接受从发布分支或热修复分支的合并
• 开发分支：dev，作为所有产品的集成开发分支，日常特性开发完成后合并至此
• 特性分支：feature/<product-scope>-<feature-name>，比如feature/storage-blob-batch-upload，明确关联目标产品，便于后续提交的作用域匹配
• 热修复分支：hotfix/<product-scope>-<fix-description>，比如hotfix/keyvault-secrets-permission-fix，针对已发布产品的紧急修复
• 发布分支：release/<product-scope>-<target-version>，比如release/storage-blob-1.3.0，用于预发布阶段的版本验证与调整

二、约定式提交语义：绑定产品作用域 #

必须通过可选作用域关联Monorepo中的具体产品，这是实现独立版本计算的核心：

• 提交格式：<type>(<product-scope>): <description>，示例：
  • feat(storage-blob): 新增批量文件上传API
  • fix(keyvault-secrets): 修复权限校验时的空指针异常
  • BREAKING CHANGE(storage-queue): 删除已废弃的队列查询接口
• 规则映射：
  • feat：对应产品的次版本号升级（如1.2.0 → 1.3.0）
  • fix/chore（修复类 chore）：对应产品的补丁版本号升级（如1.2.1 → 1.2.2）
  • BREAKING CHANGE：对应产品的主版本号升级（如1.3.0 → 2.0.0）
• 注意：若提交涉及多个产品，需拆分多个独立提交分别绑定对应作用域，禁止跨产品的单一提交

三、版本控制工具选择 #

针对Python Monorepo，推荐以下工具组合：

1. python-semantic-release
   • 支持Monorepo模式，通过根目录的pyproject.toml配置每个产品包的路径与版本规则
   • 可配置为仅扫描对应作用域的提交，计算单个产品的版本变更
   • 示例配置片段：

     [tool.semantic_release]
     monorepo = true
     packages = [
       { path = "sdk/storage/azure-storage-blob", name = "azure-storage-blob" },
       { path = "sdk/keyvault/azure-keyvault-secrets", name = "azure-keyvault-secrets" }
     ]
     

2. commitizen
   • 提供交互式提交模板，强制开发者遵循带作用域的约定式提交格式
   • 配合自定义规则，可校验提交的作用域是否为Monorepo中存在的产品包名
3. towncrier
   • 基于提交信息自动生成每个产品独立的CHANGELOG，避免跨产品的日志混淆

四、流水线自动化实现 #

实现全流程无开发者介入的版本计算与发布，核心步骤如下：

1. 变更检测：CI触发后，通过git diff对比当前分支与上一次发布的tag（需带产品前缀，如storage-blob/1.2.3），或扫描提交记录中的作用域，筛选出有变更的产品包
2. 版本计算：对每个有变更的产品，调用python-semantic-release根据提交记录计算新版本号
3. 版本更新：自动修改对应产品包的pyproject.toml/setup.py中的版本字段，生成独立的CHANGELOG文件
4. 版本标记：为每个产品的新版本创建带前缀的Git tag，如keyvault-secrets/1.4.1，避免不同产品的tag冲突
5. 打包发布：针对更新版本的产品，执行python -m build生成包文件，上传至PyPI或内部仓库
6. 提交版本变更：将版本号与CHANGELOG的修改提交回仓库（需配置CI的Git权限）

总结 #

核心原则是隔离产品版本生命周期：通过分支命名、提交作用域绑定产品，让工具能精准识别每个产品的变更；利用Monorepo支持的版本工具，结合流水线自动化，实现无需人工介入的版本管理。Azure SDK for Python正是基于类似的逻辑，通过作用域绑定每个SDK包，配合内部工具链实现批量、独立的版本发布。

内容的提问来源于stack exchange，提问作者BPL