Semantic Kernel 发布版本管理策略深度解读跨语言统一的版本号与语义化版本实践【免费下载链接】semantic-kernelIntegrate cutting-edge LLM technology quickly and easily into your apps项目地址: https://gitcode.com/GitHub_Trending/se/semantic-kernel导读本文基于仓库内的架构决策记录 0036-semantic-kernel-release-versioning.mdADR 0036系统讲解 Semantic Kernel 在多语言.NET、Java、Python生态中如何统一管理包版本号。你会了解到项目为何刻意不严格遵循语义化版本SemVer规范、MAJOR/MINOR/PATCH 分别在什么条件下递增、preview/beta/alpha等版本后缀的适用场景以及这些决策在当前仓库构建配置中的实际落地方式。读完即可准确判断某个 SK 版本号的含义并在依赖升级时做出合理决策。背景为什么需要一份专门的版本管理 ADRSemantic Kernel 是一个跨 .NET、Java、Python 的 SDK 项目每个语言生态都对应自己的包仓库.NET 包发布到 NuGetMicrosoft.SemanticKernel系列Python 包发布到 Python Package IndexPyPI包名为semantic-kernelJava 包发布到 Maven Centralcom.microsoft.semantic-kernel。当多个语言、数十个包需要同步发布时版本号如何统一变化、何时递增、何时允许破坏性变更就必须有一份明确的、被整个团队认可的策略——这正是 ADR 0036 的存在意义。这份 ADR 由markwallace负责维护决策者包括sergeymenshykh、markwallace、rbarreto、dmytrostruk并咨询了matthewbolanos其内容适用于 .NET、Java、Python 三个语言版本在包达到 v1.0 之后。说明从当前仓库 java/README.md 可以看出Java 版本的开发后来已迁移至独立的semantic-kernel-java仓库但各语言版本仍保持同步对齐发展本文所述版本策略对 Java 版本依然适用。决策一不严格遵循语义化版本规范决策要点ADR 0036 明确声明Semantic Kernel 不会严格遵循语义化版本规范SemVer。理由很直接——NuGet 包生态本身就未严格遵守该规范完全套用 SemVer 的严格规则反而不利于生态一致性。这一决策带来了三条配套约定不兼容的 API 变更记录在发布说明中如果某个版本包含不兼容的 API 变更即使这些变更不足以触发 MAJOR 版本递增也会在 release notes 中明确文档化让升级者能提前感知风险。大多数常规更新以新增功能为主项目预期绝大多数常规发布都是新增功能 向后兼容因此版本号以 MINOR 递增为主基调而不是频繁的大版本跳变。低影响不兼容变更不触发 MAJORADR 特别定义了一种例外——低影响不兼容的 API 变更low impact incompatible API changes。这类变更通常只影响 Semantic Kernel 内部实现或单元测试不会对公开 API 面造成显著扰动因此不递增 MAJOR 版本。ADR 同时强调团队并不预期对 Semantic Kernel 的 API 表面做出重大改动。对使用者的意义这条决策意味着升级 SK 版本时不能只依赖MAJOR 版本未变 无破坏性变更的直觉而应把发布说明作为权威依据。即使是从1.x升到1.(x1)也应先扫一遍 release notes 中标注的 breaking changes。决策二所有包使用同一版本号同进同退Semantic Kernel 在版本号上采取全家桶策略这是整套版本管理中最重要的工程约定统一版本号每次发布新版本时所有包使用完全相同的版本号。全部重新发布所有包都包含在每一次发布中即使某个包本次没有任何代码改动其版本号也会一并递增。发布前全量测试每次发布都会进行测试确保所有包彼此兼容。官方支持的同版本组合项目推荐客户使用相同版本的包组合这也是官方会持续支持的配置形态。仓库中的落地证据这一决策在 .NET 侧的构建配置中体现得非常具体。看 dotnet/nuget/nuget-package.props它通过一个中央版本前缀统一驱动所有包!-- Central version prefix - applies to all nuget packages. -- VersionPrefix1.80.0/VersionPrefix PackageVersion Condition$(VersionSuffix) ! $(VersionPrefix)-$(VersionSuffix)/PackageVersion PackageVersion Condition$(VersionSuffix) $(VersionPrefix)/PackageVersion注释明确写着 Central version prefix - applies to all nuget packages——所有 NuGet 包的版本都由同一个VersionPrefix派生后缀如-preview则通过VersionSuffix附加。这正是所有包同版本号的工程化实现。同时仓库采用 NuGet 的**集中包管理Central Package Management**机制见 dotnet/Directory.Packages.props启用ManagePackageVersionsCentrally由 dotnet/Directory.Build.targets 将版本统一约束到所有项目。在 dotnet/Directory.Packages.props 中可以看到 SK 自身包的依赖版本全部对齐到同一版本号PackageVersion IncludeMicrosoft.SemanticKernel.Abstractions Version1.71.0 / PackageVersion IncludeMicrosoft.SemanticKernel.Connectors.OpenAI Version1.71.0 / PackageVersion IncludeMicrosoft.SemanticKernel.Core Version1.71.0 /可以看到Abstractions、Core、Connectors.OpenAI等基础包都是1.71.0——即使它们各自独立演进对外发布的版本号始终保持一致。而Microsoft.SemanticKernel.Planners.OpenAI为1.47.0-preview则是预览后缀在依赖清单中的真实写照详见下文版本后缀部分。对使用者的意义引用 SK 包时尽量让所有 SK 包保持同一版本这是官方声明支持的配置混搭不同版本虽然技术上可行但不在官方支持范围之内。如果你只用到其中一个包但每次发布所有包都会递增版本那么升级时看到无关包也升版本是正常现象并非发布失误。决策三MAJOR / MINOR / PATCH 的递增规则ADR 0036 为版本号的三个组成部分划定了清晰的递增条件版本位递增条件典型场景MAJOR不因低影响不兼容 API 变更递增不因实验功能或 alpha 包的 API 变更递增重大架构重构、大规模 API 面调整项目预期很少发生MINOR以向后兼容的方式新增功能新增 Kernel 能力、新增连接器、新增插件 API是大多数常规发布的形态PATCH截止发布时仅包含向后兼容的 bug 修复缺陷修复、性能修复、文档修正不引入新功能需要特别强调的是两个不递增 MAJOR的例外低影响不兼容变更ADR 的脚注澄清这类变更通常只影响 Semantic Kernel 内部实现或单元测试团队预期不会对 SK 的 API 表面做重大改动。因此这类变更可以安全地发生在 MINOR 或 PATCH 版本中并通过发布说明告知。实验功能与 alpha 包实验性功能、alpha 包的 API 处于快速演进期其变更不受 MAJOR 版本递增的约束。这保证了实验功能可以高频迭代而不拖累正式 API 的版本节奏。源码佐证版本验证基线dotnet/nuget/nuget-package.props 中有一项PackageValidationBaselineVersion是这一策略在构建层面的配套!-- Package validation. Baseline Version should be the latest version available on NuGet. -- PackageValidationBaselineVersion1.79.0/PackageValidationBaselineVersion它声明当前最新可用版本作为验证基线当前仓库快照中为 1.79.0而VersionPrefix为 1.80.0二者相差一个 MINOR 版本构建时对包进行 API 兼容性验证——这正体现了虽然不严格遵循 SemVer但仍用工具保障向后兼容的思路版本策略可以灵活但兼容性底线不会放松。决策四版本后缀体系——preview、beta 与 alphaADR 0036 定义了两种主要版本后缀语义差异非常明确preview与beta接近发布含义用于接近正式发布的包。例如版本1.x.x-preview表示该包已接近其1.x正式版。成熟度功能已完整feature complete接口与正式版本非常接近。语言差异.NET发布使用preview后缀Python发布使用beta后缀。二者语义等价只是各语言生态的习惯命名不同。alpha功能不完整、接口未定型含义用于功能尚不完整的包公开接口仍处于开发中、预期会发生变化。成熟度远未达到发布标准属于早期实验阶段。注意alpha 包的 API 变更不受 MAJOR 版本递增约束见上文使用时需预期破坏性变更。仓库中的实例.NET 侧依赖清单 dotnet/Directory.Packages.props 中Microsoft.SemanticKernel.Planners.OpenAI版本为1.47.0-preview是preview后缀在仓库中的直接实例。此外仓库中的 MCPModel Context Protocol等集成包也大量使用-preview后缀。Python 侧版本号从 python/semantic_kernel/init.py 的__version__动态读取对应 python/pyproject.toml 中dynamic [version]的声明当前快照为1.44.1并额外定义了候选发布版本__version__ 1.44.1 DEFAULT_RC_VERSION f{__version__}-rc9这里的rcRelease Candidate发布候选后缀可以看作beta到正式版之间的最后一道门槛功能与接口已冻结只待验证通过即转正。配合 ADR 的后缀体系Python 包的版本生命周期大致为alpha功能开发中→beta/rc接近发布→ 正式版。决策五发布说明是版本策略的配套承诺ADR 0036 将文档化不兼容变更作为与版本号体系并行的配套机制。由于 MAJOR 版本不会因为低影响不兼容变更而递增release notes 就承担了向开发者披露破坏性变更的职责。这意味着升级 SK 时发布说明release notes应被视为第一手依据遇到小版本号 破坏性变更的组合不必惊讶这是 ADR 明示的策略对于追求稳定性的生产项目可以优先选择最近一段时间内以 PATCH 递增为主的版本这类版本只包含向后兼容的 bug 修复。总结如何读懂一个 Semantic Kernel 版本号综合 ADR 0036 的全部决策可以给出一个实用的版本号解读流程看后缀alpha表示接口未定型、慎用于生产preview.NET/betaPython表示功能已冻结、接近发布、可评估使用rc是发布候选无后缀即正式版。看 MINOR 位大多数常规发布通过 MINOR 递增带来新功能同时保持向后兼容——这是最常见的升级路径。看 PATCH 位如果从上次升级到现在只有 PATCH 递增说明期间只包含向后兼容的 bug 修复升级风险最低。看发布说明由于不严格遵循 SemVer判断是否有破坏性变更的权威来源不是版本号本身而是随版本发布的 release notes。保持同版本引用多个 SK 包时将它们锁定在同一版本号这是官方支持并推荐测试的配置。这套策略的本质是在语义化版本的严格性与跨语言多包同步发布的可操作性之间做出的务实取舍用统一的版本节奏换取生态内的一致性用发布说明换取变更透明度用兼容性验证如包验证基线守住向后兼容的底线。延伸阅读仓库 docs/decisions 目录下还收录了 70 余份 ADR其中 0045-breaking-changes-guidance.md 与版本管理直接相关进一步细化了破坏性变更的处理规范可作为本文的配套阅读。【免费下载链接】semantic-kernelIntegrate cutting-edge LLM technology quickly and easily into your apps项目地址: https://gitcode.com/GitHub_Trending/se/semantic-kernel创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考