把 Helm 当 Go SDK 依赖时，如何判断 pkg/ 公共 API 的跨版本向后兼容边界？
【免费下载链接】helmThe Kubernetes Package Manager项目地址: https://gitcode.com/GitHub_Trending/hel/helm
如果你的 Go 项目直接 importhelm.sh/helm/v4的包来做 chart 渲染、release 管理、chart 仓库交互等 SDK 级操作，每次升级 Helm 依赖前都要回答一个问题：我正在用的这些符号，哪些在跨版本升级时受项目承诺保护，哪些可能随时改变。Helm 仓库没有单独的 docs 目录，官方兼容性承诺集中在 CONTRIBUTING.md 的 "Semantic Versioning" 章节和 AGENTS.md 的 "Compatibility" 章节，本文的判定标准全部来自这两份文档。
公共 API 的边界：pkg/ 目录
AGENTS.md 开篇说明代码库同时支持两种用法："an SDK for advanced users, and a CLI for direct end user usage"。在 "Code structure" 一节中，pkg/被直接标注为 Public API，其中列出的主要包包括：
action/— 核心操作（install、upgrade、rollback）chart/v2/— 稳定的 chart 格式engine/— 模板渲染（Go templates + Sprig）kube/— Kubernetes 客户端抽象层registry/— OCI 支持release/— release 类型与接口repo/— chart 仓库索引与交互storage/— release 后端（Secrets/ConfigMaps/SQL）
同一份文档的 "Compatibility" 章节要求：
- 公共 API 的签名——即
pkg/目录中的那些——不应改变； - CLI 命令和参数不应以破坏现有脚本或工作流的方式删除或更改；
- 功能行为（隐含或文档化的）不得以破坏现有用户预期的方式修改。
CONTRIBUTING.md 在 "Semantic Versioning" 章节给出同样方向的承诺：项目承诺"不以后向不兼容的方式更改pkg/目录内公开可访问的 Go 库定义"，同时明确cmd/和internal/中的代码"may be changed from release to release without notice"（可以不通知地在版本间更改）。
由此得到第一条判定边界：一个符号的 import 路径落在pkg/之下，才处于向后兼容承诺内；仓库顶层的cmd/（CLI 入口 cmd/helm/）与internal/（私有实现）不参与承诺。注意pkg/cmd/虽然也带 "cmd" 字样，但它位于pkg/之下，在 AGENTS.md 中被归入公共 API 包列表（其定位是"Cobra 命令实现，桥接 CLI flags 到pkg/action/"）。
项目承诺的兼容规则
CONTRIBUTING.md 给出的 3.0 到 4.0 之间的后向兼容规则摘要如下（引自原文 "a quick summary of our backward compatibility guidelines for releases between 3.0 and 4.0"）：
| 项目 | 承诺 |
|---|---|
| 命令行命令、flags、参数 | MUST 后向兼容 |
| 文件格式（如 Chart.yaml） | MUST 后向兼容 |
| Chart 兼容 | 在旧版 Helm 3 上能工作的 chart，MUST 在新版 Helm 3 上继续工作；文档给出的两个例外是：(a) Kubernetes 本身发生了变化，(b) 该 chart 是因为利用了某个 bug 才恰好能工作 |
| Chart 仓库功能 | MUST 后向兼容 |
pkg/内的 Go 库 | MUST 保持后向兼容；而cmd/与internal/中的代码可以不通知地更改 |
同一段落还说明："All of our changes to protocols and formats are backward compatible from one major release to the next"——协议与格式层面的变更从一个主版本到下一个主版本保持后向兼容，前提是无需修复安全问题。
文档中记录的唯一例外在 AGENTS.md："An exception to the above is where incompatible changes are needed to fix a security vulnerability, where minimal breaking changes may be made to address the issue."——当修复安全漏洞需要不兼容变更时，项目允许做最小的破坏性修改。
CONTRIBUTING.md 同时指向 HIP-0004 作为 minor 与 patch 版本级兼容规则的详细来源；该 HIP 的正文不在本仓库中，涉及细粒度规则时需要另行查阅。
先定位你的依赖处在哪个主版本线
判定之前先确认自己依赖的是哪条版本线，因为承诺的适用范围与主版本绑定：
- go.mod 第一行声明模块为
helm.sh/helm/v4，go指令为1.26.0——依赖当前 main 分支线意味着模块路径带/v4主版本后缀，且需要至少该版本要求的 Go 工具链。 - README.md 说明：Helm v4 是当前稳定版，在
main分支开发；Helm v3 处于支持模式，在dev-v3分支上，bug 修复到 2026 年 7 月 8 日，安全修复到 2026 年 11 月 11 日。 - AGENTS.md "Branching" 一节给出分支结构：
main对应 Helm v4，dev-v3对应 Helm v3（从 main 回移安全修复与 bugfix），release 分支命名为release-v3.X与release-v4.X。 - 关于不兼容变更的处理，CONTRIBUTING.md 写明：被判定为后向不兼容的 issue/PR 可以带
label:v4.x标签加入 Helm 4 的讨论项——也就是说，计划中的破坏性变更会落到下一个主版本的讨论中，而不是混入当前主版本的 minor/patch 发布。
在你自己项目中执行判定
以下命令在你自己的 Go 项目根目录运行（不是 Helm 仓库，本仓库为只读资料），用来枚举所有对 Helm 模块的引用：
grep -rn "helm.sh/helm" --include="*.go" .然后逐条处理输出的 import 路径：
- 路径落在模块路径的
pkg/之下（例如helm.sh/helm/v4/pkg/action、.../pkg/chart/v2、.../pkg/registry）：处于向后兼容承诺范围内，跨 minor/patch 版本升级时这些 Go 库定义的稳定性受 CONTRIBUTING.md 与 AGENTS.md 承诺约束。 - 路径指向顶层
cmd/或internal/：无兼容承诺，文档明确允许不通知地更改；其中internal/在 Go 模块机制下本来也不作为外部模块的稳定接口。 - 比对模块路径中的主版本：
helm.sh/helm/v4中的/v4决定你所处的版本线。上述 "MUST 后向兼容" 的 pkg/ 规则在 CONTRIBUTING.md 中的表述范围是 3.0 到 4.0 之间的发布；如果你同时维护 v3 线依赖（dev-v3），注意该线已进入支持模式，只接收 bug 与安全修复，不再有新功能。
判定结论与限制
- 判定结果是二元的：你依赖的符号只要全部位于
pkg/之下、且保持在同一主版本模块路径内，就处于文档承诺的保护范围内；否则视为不稳定接口，升级前应逐个人工核对变更。 - 已记录的唯一例外是安全修复：AGENTS.md 允许安全漏洞修复携带"minimal breaking changes"，因此即使是 pkg/ 下的符号，跨越安全修复版本升级时也不能假设零破坏。
- 本文核对过的三份文档（README.md、CONTRIBUTING.md、AGENTS.md）都没有记录自动化的 API 兼容性检查命令；兼容性判定只能依据上述边界规则完成，minor/patch 级的更细规则需要查阅 CONTRIBUTING.md 引用的 HIP-0004。
- 仓库不提供 docs 目录，SDK 用法本身没有独立的教程文档；
pkg/各子包的能力以 AGENTS.md "Code structure" 的包列表和各包源码为准。
【免费下载链接】helmThe Kubernetes Package Manager项目地址: https://gitcode.com/GitHub_Trending/hel/helm
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
