## 一、版本管理规范 ### 1.1 版本号规则火山引擎 SDK（Go SDK 除外）遵循**语义化版本（Semantic Versioning, SemVer）** 规范，版本号格式为 X.Y.Z： * **主版本号 X**：引入不兼容的 API 变更（Breaking Changes）或底层架构重大调整时递增 * **次版本号 Y**：引入向后兼容的新功能（如支持新的云服务或新特性）时递增 * **修订号 Z**：进行向后兼容的缺陷修复或安全补丁时递增 **示例：** 从版本 1.3.2 升级到 1.4.0 表示新增了向后兼容的功能；而从 1.x 升级到 2.0.0 则表示存在不兼容的变更，需参考迁移指南进行适配。 ### 1.2 主版本生命周期每个 SDK 主版本都有明确的生命周期阶段，确保开发者能合理规划版本切换： |**阶段** |**持续时间** |**说明** | |---|---|---| |**开发者预览** |不定 |早期开发 / Beta 测试状态，不提供正式技术支持，可能引入不兼容变更。严禁用于生产环境。 | |**正式可用（GA）** |≥ 24 个月 |SDK 达到稳定状态。提供全量功能更新，包括新服务支持、API 增强、Bug 修复与安全补丁。 | |**维护公告** |≥ 6 个月 |在进入维护模式前发布正式公告。此阶段 SDK 仍处于全量支持状态。 | |**维护阶段** |默认 12 个月 |仅修复严重 Bug 和高危安全漏洞。不再提供新服务支持或新 Region 上线。 | |**终止支持（EoS）** |— |该主版本正式退役，不再接收任何更新。历史版本仍保留在公共包管理器中。 | ## 二、更新与升级政策 ### 2.1 更新频率 * **功能更新**：随云产品 API 发布节奏持续更新，通常每周至每两周发布一个新版本 * **安全补丁**：发现高危漏洞后 72 小时内发布紧急修复 * **Bug 修复**：根据严重程度在 1\-4 周内修复并发布 ### 2.2 兼容性承诺 **核心承诺：** 在同一主版本内，我们确保向后兼容。次版本和修订版本的升级不会破坏现有业务代码。 **以下变更被视为兼容性变更（不提升主版本号）：** * 新增可选参数 * 新增响应字段 * 新增服务 API 方法 * 修复文档中未承诺的行为差异 * 性能优化 **以下变更被视为不兼容变更（需提升主版本号）：** * 删除或重命名公开 API 方法 * 修改参数类型或必填性 * 修改方法签名 * 删除响应字段 * 修改错误码含义 ### 2.3 升级建议 **我们强烈建议用户始终将 SDK 保持在最新稳定版本**，以获得： * 最新的云服务 API 支持 * 安全漏洞修复 * 性能优化和稳定性提升 * 新功能特性 ## 三、运行时支持基线 SDK 运行在特定的底层环境之上，包括语言运行时、操作系统及第三方库。我们的基本政策是：**在底层依赖社区宣布 EOL 后，继续提供至少 6 个月的支持缓冲期**。 ### 3.1 各语言运行时最低版本 |**语言** |**最低支持版本** |**推荐版本** |**废弃缓冲原则** | |---|---|---|---| |**Go** |开发者当前使用的主流版本中较老的一个（当前是：**1.18**）。 |最新 Go GA 版本（如 Go 1.24+） |社区 EOL 后保留 6\-12 个月缓冲 | |**Java** |Java 8 (LTS) |Java 17 或 Java 21 LTS |LTS EoL 后继续支持至少 12 个月 | |**Python** |Python 3.10（仅支持 PSF 维护窗口内版本） |Python 3.12 或 3.13+ |EoL 后继续支持至少 12 个月 | |**PHP** |PHP 8.1+ |PHP 8.2 或 8.3+ |官方安全支持结束后继续支持 12 个月 | |**Node.js** |Node.js 20+（Active LTS） |Node.js 22 或 24 LTS |LTS EoL 后保留 8\-12 个月缓冲 | ### 3.2 运行时版本提升决策原则我们在决定提升最低运行时版本时，会综合评估以下因素： * **社区状态**：底层运行时距离 EOL 的时间 * **用户占比**：仍在使用旧版本的用户比例 * **安全与合规**：是否存在无法修复的安全漏洞 * **维护成本**：维护旧版本兼容性的技术成本 ## 四、废弃与迁移 ### 4.1 废弃流程当 SDK 功能、参数或版本需要废弃时，我们遵循以下标准流程： * **发布公告**：通过官方文档、SDK中心通知受影响的开发者。 * **缓冲期**：至少保留 6 个月的废弃缓冲期，确保开发者有充足时间迁移。 * **正式移除**：在下一个主版本中移除废弃的功能。 ### 4.2 迁移支持对于主版本升级，我们提供： * **迁移指南文档**：详细说明不兼容变更及迁移步骤 * **代码示例**：新版本的完整代码示例 * **迁移工具**：部分语言提供自动化迁移脚本 * **技术支持**：通过工单提供迁移咨询 ## 五、沟通与通知渠道我们通过以下渠道向开发者传递 SDK 生命周期变更信息： * **官方文档**：在火山引擎 SDK 官方文档和 [GitHub README ](https://github.com/volcengine/volcengine-go-sdk)中更新版本支持信息。 * **SDK中心：** 在[火山引擎 SDK中心](https://api.volcengine.com/api-sdk)站点的公告中更新版本支持信息。

火山引擎SDK