API 演进和版本控制
本文档涵盖 OpenLayers 的 API 演进、版本管理和在引入新功能和改进时保持稳定性的方法。它解释了如何管理破坏性更改、弃用策略，以及支持跨主要版本平滑升级的工具和过程。
有关构建系统和发布基础设施的信息，请参阅构建系统和工具。
版本控制策略
OpenLayers 遵循语义化版本控制原则，对跨主要版本的 API 演进采用结构化方法。版本管理系统在为生产应用程序提供稳定性关注点的同时平衡创新。
版本号结构 当前开发版本遵循 Major.Minor.Patch-dev 模式，其中 -dev 后缀表示朝向下一次发布的正在进行开发工作。
主要版本更改 主要版本引入需要代码修改的破坏性更改。示例包括：
- 删除已弃用的类，如
ol/layer/MapboxVector - 核心类中的 API 签名更改
- 模块重组和导入路径更改
- 影响现有应用程序的默认行为更改
API 稳定性分类
OpenLayers 为 API 的各个部分维护不同的稳定性级别，帮助开发人员了解哪些功能对于生产使用是安全的，哪些可能会更改。
稳定的 API 组件 核心地图功能，包括 ol/Map、ol/View、图层类型和源类型，在主要版本内保持向后兼容性。
实验性功能 像 WebGLPointsLayer 这样的功能被明确标记为实验性的，可能会在次要版本之间进行破坏性更改。升级说明特别提到："请注意，WebGLPointsLayer 不是稳定 API 的一部分，在主要版本之间可能会进行破坏性更改。"
内部 API WebGL 工具类和构建系统组件被认为是内部的，可能会在无通知的情况下更改。
弃用生命周期
OpenLayers 遵循结构化的弃用过程，在删除功能之前提供提前警告，允许开发人员有时间迁移其应用程序。
弃用时间线 功能通常在下一个主要版本中删除之前弃用 1-2 个次要版本。这提供了足够的迁移时间，同时保持开发势头。
迁移文档 每个弃用都包括详细的迁移说明，包含前/后代码示例。例如，从 WebGLPointsLayer 到 WebGLVectorLayer 的转换包括完整的配置示例，展示如何重新构构样式和过滤器选项。
控制台警告 已弃用的 API 在开发构建中生成控制台警告，以提醒开发人员即将进行的更改。
破坏性更改管理
破坏性更改经过仔细管理和记录，以最小化升级摩擦，同时实现 API 的必要改进。
方法签名更改 当方法签名更改时，升级说明提供确切的示例。例如，getFeaturesInExtent() 从 ol/source/VectorTile 移动到 ol/layer/VectorTile 显示了旧的和新的调用模式：
// 之前
layer.getSource().getFeaturesInExtent(extent);
// 之后
layer.getFeaturesInExtent(extent);配置更改 复杂的配置更改（如 WebGL 样式格式演变）包括全面的示例，展示如何为新 API 重新构架现有配置。
行为更改 默认行为的更改有明确的文档记录，并附有在需要时保持以前行为的说明。
版本发布工作流程
发布过程集成了版本管理与变更日志生成和 API 文档更新。
变更日志维护 changelog/upgrade-notes.md 文件作为 API 更改和迁移指导的权威来源。每个主要版本部分记录破坏性更改、新功能和升级说明。
包版本管理 package.json 版本字段遵循语义化版本控制，-dev 后缀表示未发布的开发版本。
发布协调 版本发布协调多个工件的更新，包括 NPM 包、文档和示例应用程序。
迁移支持工具
OpenLayers 提供了几种机制来支持跨主要版本边界的平滑迁移。
| 迁移工具 | 目的 | 位置 |
|---|---|---|
| 升级说明 | 全面的更改文档 | changelog/upgrade-notes.md |
| 代码示例 | 前/后迁移模式 | 嵌入在升级说明中 |
| 控制台警告 | 运行时弃用警报 | 开发构建 |
| 类型定义 | TypeScript 迁移支持 | 生成的 .d.ts 文件 |
全面的文档 升级说明为每个破坏性更改提供详细的迁移说明，包括完整的代码示例，展示如何更新应用程序代码。
增量迁移 破坏性更改分批到主要版本中，允许开发人员规划迁移工作并系统地更新应用程序，而不是不断追逐 API 更改。
TypeScript 支持 类型定义有助于在编译时捕获破坏性更改，使迁移更可靠并减少运行时错误。