API Evolution and Versioning
This document covers OpenLayers' approach to API evolution, version management, and maintaining stability while introducing new features and improvements. It explains how breaking changes are managed, deprecation policies, and the tools and processes that support smooth upgrades across major versions.
For information about the build system and release infrastructure, see Build System and Tooling.
Versioning Strategy
OpenLayers follows semantic versioning principles with a structured approach to API evolution across major versions. The version management system balances innovation with stability concerns for production applications.
Version Number Structure The current development version follows the pattern Major.Minor.Patch-dev, where the -dev suffix indicates ongoing development work toward the next release.
Major Version Changes Major versions introduce breaking changes that require code modifications. Examples include:
- Removal of deprecated classes like
ol/layer/MapboxVector - API signature changes in core classes
- Module reorganization and import path changes
- Changes to default behaviors that affect existing applications
API Stability Classification
OpenLayers maintains different stability levels for various parts of the API, helping developers understand which features are safe for production use and which may change.
Stable API Components Core mapping functionality including ol/Map, ol/View, layer types, and source types maintain backward compatibility within major versions.
Experimental Features Features like WebGLPointsLayer are explicitly marked as experimental and may undergo breaking changes between minor releases. The upgrade notes specifically mention: "Note that the WebGLPointsLayer is not part of the stable API and is subject to breaking changes between major releases."
Internal APIs WebGL utility classes and build system components are considered internal and may change without notice.
Deprecation Lifecycle
OpenLayers follows a structured deprecation process that provides advance warning before removing features, allowing developers time to migrate their applications.
Deprecation Timeline Features are typically deprecated for 1-2 minor versions before removal in the next major version. This provides sufficient time for migration while maintaining development momentum.
Migration Documentation Each deprecation includes detailed migration instructions with before/after code examples. For instance, the transition from WebGLPointsLayer to WebGLVectorLayer includes complete configuration examples showing how to restructure style and filter options.
Console Warnings Deprecated APIs generate console warnings in development builds to alert developers about upcoming changes.
Breaking Change Management
Breaking changes are carefully managed and documented to minimize upgrade friction while enabling necessary improvements to the API.
Method Signature Changes When method signatures change, the upgrade notes provide exact examples. For instance, the move of getFeaturesInExtent() from ol/source/VectorTile to ol/layer/VectorTile shows the old and new calling patterns:
// Before
layer.getSource().getFeaturesInExtent(extent);
// After
layer.getFeaturesInExtent(extent);Configuration Changes Complex configuration changes, like the WebGL style format evolution, include comprehensive examples showing how to restructure existing configurations for the new API.
Behavioral Changes Changes to default behaviors are clearly documented with instructions for maintaining previous behavior when needed.
Version Release Workflow
The release process integrates version management with changelog generation and API documentation updates.
Changelog Maintenance The changelog/upgrade-notes.md file serves as the authoritative source for API changes and migration guidance. Each major version section documents breaking changes, new features, and upgrade instructions.
Package Version Management The package.json version field follows semantic versioning, with the -dev suffix indicating unreleased development versions.
Release Coordination Version releases coordinate updates across multiple artifacts including NPM packages, documentation, and example applications.
Migration Support Tools
OpenLayers provides several mechanisms to support smooth migrations across major version boundaries.
| Migration Tool | Purpose | Location |
|---|---|---|
| Upgrade Notes | Comprehensive change documentation | changelog/upgrade-notes.md |
| Code Examples | Before/after migration patterns | Embedded in upgrade notes |
| Console Warnings | Runtime deprecation alerts | Development builds |
| Type Definitions | TypeScript migration support | Generated .d.ts files |
Comprehensive Documentation The upgrade notes provide detailed migration instructions for every breaking change, including complete code examples showing how to update application code.
Incremental Migration Breaking changes are batched into major versions, allowing developers to plan migration work and update applications systematically rather than continuously chasing API changes.
TypeScript Support Type definitions help catch breaking changes at compile time, making migrations more reliable and reducing runtime errors.