开源项目发版本这事，看着简单——打个tag、改个changelog、push上去就行了。真到实际操作的时候，每个环节都能给你整出点意外。

release-management 这个仓库就是来解决这些问题的。它本质上是昇腾CANN社区的发布规范层，把版本号怎么定、changelog 怎么写、发布流程怎么跑这些问题固化下来，避免每个 maintainer 各搞各的。

版本号怎么定：semantic versioning 的坑

我最开始用 release-management 的时候，觉得语义化版本（semver）就是 主版本.次版本.补丁 三段数字，写规范点就行。后来踩了一个坑才明白，次版本号递增意味着"向后兼容的新功能"——但什么叫向后兼容？

当时我给 ops-nn 仓库加了一个新融合模式，顺手把原有 API 的参数顺序改了，以为这是"小改动"，打了 1.1.0 的 tag。结果下游 cann-recipes-infer 直接崩了，因为它用了命名参数传参，参数顺序一变直接报错。用户 issue 刷过来的时候我还觉得奇怪，明明是个"小功能"怎么把别人跑得好好的 pipeline 搞挂了。

后来 release-management 的规范帮我理清了：

# 主版本号（MAJOR）：API 不兼容变更
# 典型场景：参数删除、参数顺序变更、返回值类型变化
MAJOR = 2  # 这次是 2.0.0，不兼容升级

# 次版本号（MINOR）：向后兼容的新功能
# 典型场景：新增可选参数、新增 API、不改变现有调用方式
MINOR = 1

# 补丁版本号（PATCH）：向后兼容的问题修复
# 典型场景：bugfix、文档更新、不改变任何行为
PATCH = 0

核心判断标准就一条：用户的旧代码不修改直接跑，能跑通吗？ 跑不通就是主版本变更，打 X.0.0。

changelog 生成：手动写 vs 自动化的差距

之前写 changelog 是真痛苦，每次发版要翻 commit history，对照 commit message 整理 Feature/Fix/Change，然后把内容粘进 CHANGELOG.md。commit message 写得不规范的还得回溯代码逻辑，工作量不大但极其烦人。

release-management 的自动生成逻辑大概是这样的：

from release_management import ChangeLog

# 指定从哪个 tag 到哪个 tag 生成 changelog
changelog = ChangeLog.generate(
    repo="ops-transformer",
    from_tag="v1.2.0",
    to_tag="v2.0.0",
    # categories 控制分组粒度
    categories=["feat", "fix", "perf", "docs"]
)

print(changelog)

输出大概长这样：

## v2.0.0 (2026-01-15)

### Breaking Changes
- 参数 `fused_attention` 替换为 `attention_mode`，旧参数不再支持

### New Features
- 新增 FlashAttention-v2 实现，上下文长度支持到 32K
- 新增 MoE 稀疏路由算子，支持 Top-8 激活

### Performance
- 注意力计算吞吐提升 37%（A910，实测）
- 显存占用降低 22%（128K 上下文场景）

### Bug Fixes
- 修复 TopK 路由在奇数专家数时的越界问题

commit message 规范的话，这个生成质量其实还不错。commit message 乱写的话，生成的 changelog 也跟天书一样——所以规范要先建好，工具只是放大镜。

发布流程自动化：Pipeline 怎么跑

最让我头疼的是发布流程本身。测试、打包、生成 changelog、创建 release、通知贡献者，这些步骤里任何一个手动操作都可能引入错误——忘记跑测试就发版、打包漏了文件、tag 打错版本号。

release-management 的 Pipeline 把这些串成自动流程：

from release_management import ReleasePipeline

pipeline = ReleasePipeline(
    repo="ops-nn",
    version="2.0.0",
    # dry_run 先验证流程，不实际操作
    dry_run=True
)

# 分步执行，每步都有回滚能力
pipeline.run_tests()          # 自动跑单元测试 + 集成测试
pipeline.check_dependencies() # 验证 CANN 版本兼容性
pipeline.build_packages()     # 构建 whl/tar.gz
pipeline.generate_changelog()# 从 commit 生成 changelog
pipeline.create_release()     # 创建 GitHub/Gitee release
pipeline.notify_committers()  # 邮件/站内信通知贡献者

dry_run=True 这个参数设计得很实用。每次正式发布前先跑一遍 dry run，看看哪一步会报错，避免发布到一半卡住。特别是依赖检查那步，有时候你本地装的 CANN 版本和 CI 环境不一样，dry run 能在本地先发现问题。

tag 管理：最容易出事的环节

发布流程里最容易翻车的是 tag 管理。Git tag 和 release 对象要保持同步，版本号打错的话要删掉重建，一不小心就留了个脏 tag 在仓库里。

release-management 的 tag 策略是这样的：

# 强制 tag 签名验证，防止标签被篡改
# 每次发布前验证 tag 存在且签名有效
from release_management import TagManager

tm = TagManager(repo="ops-transformer")

# 验证 tag 完整性
is_valid = tm.verify_tag("v2.0.0")
print(f"Tag v2.0.0 有效: {is_valid}")

# 如果版本号打错了，需要先删除再重建
if not is_valid:
    tm.delete_tag("v2.0.0")  # 本地 + 远程同时删除
    tm.create_tag("v2.0.0", message="Release v2.0.0", sign=True)

实际踩过的坑：本地 tag 打好了，push 的时候网络断了，半截的 tag push 到一半。远程有一个残缺的 tag，本地也有一份，两个状态不一致。这种情况 git fetch --prune 能清理掉无效 tag，但发布流程里应该加个幂等检查——tag 存在就跳过，不存在才创建。

一点感受

release-management 这个仓库在 CANN 五层架构里属于最外层的开发支持部分，平时存在感不强，但真到发版的时候少了他要么手忙脚乱，要么出事故。

社区贡献的时候也绕不开它——提 PR 要符合 commit message 规范，发版本要走 Pipeline，这些约束看起来麻烦，实际上是在保护 maintainer 和用户双方。规范先行，工具跟上，这是最省力的方式。

仓库在 https://atomgit.com/cann/release-management，有完整的发布流程文档可以参考。