Introducing semantic versioning
We’re excited to announce a major change in how we version and release the ArcGIS Maps SDK for JavaScript: we’re moving to semantic versioning (SemVer)! This change will make it easier for developers to upgrade between versions, understand release impacts, plan upgrades, and integrate with modern tooling.
What is semantic versioning?
Semantic versioning uses a simple format: MAJOR.MINOR.PATCH.
- MAJOR: Breaking changes or deprecations. Upgrading may require code changes.
- MINOR: Backward-compatible feature additions or deprecations. Safe to upgrade.
- PATCH: Backward-compatible bug and security fixes. No new features or deprecations.
While our legacy versioning (e.g., 4.33, and 4.33.12 in the case of npm releases) looks similar, it simply represents a new iteration of the SDK. Every release includes breaking changes. In contrast, when following SemVer, the version number instantly signals the nature of the release.
Why move to SemVer?
Here’s what developers gain:
- Instant risk signaling: One glance at the version tells you if you can auto-merge or need to schedule work.
- Risk flag: Major versions require reviewing migration guides before upgrading.
- Better planning: Disruptive changes are batched into predictable timeframes.
- Value drip: Get enhancements by upgrading to new minor releases without fear of breakage.
- Safe auto-upgrade: Default version ranges (e.g., ^5.1.0) pick up new minors automatically.
- Deprecation runway: Clear warnings when APIs will be removed in the next major release.
- Tooling alignment: npm, Yarn, Renovate, Dependabot, and CI policies all work seamlessly with SemVer.
- Lower support and integration cost: Fewer silent breaks, clearer upgrade guides, faster security fixes.
Release schedule
Version 4.34 is right around the corner (releasing this month) and will be the last release of the 4.x series. Don’t be alarmed! Moving to 5.x is driven by the introduction of semantic versioning 🙂
Starting in 2026, our release plan includes one major version and two minor versions per year:
- February: Major version (5.0 instead of 4.35)
- June & October: Minor versions (5.1 and 5.2)
- February 2027: Next major (6.0)
This predictable cadence helps you plan upgrades and batch disruptive work.
Support plan
Our Product Lifecycle Policy (PLC) will evolve with this new release strategy as follows:
- A new release will be in general availability until the next minor release.
- Extended support continues for three years from the initial major release (MAJOR.0).
- Patches for bugs are applied to the latest minor of a supported major version (MAJOR.LATEST).
- We will be removing the mature support phase, in alignment with the recent changes to ArcGIS Enterprise’s PLC.
The new support plan will not impact prior releases, including version 4.34.
Alignment with Calcite
For several years, JavaScript Maps SDK and ArcGIS Online have been delivered with coordinated releases as the two software entities build on each other. Online is enhanced with more workflows using new functionality in the SDK and the SDK is updated to access new Online functionality at the same time. They evolve together. Online, the SDK, and many developers building custom apps with the SDK also heavily rely on Calcite Design System for layout and UI elements that construct the UI/UX. To enable smoother integration across the stack, this year we aligned Calcite releases with the SDK and Online. In addition, as Calcite is already following SemVer, we will align major releases with the SDK’s major releases.
Conclusion
Semantic versioning gives you greater clarity, confidence, and control. Our goal is to help clarify when breaking changes happen, streamline the upgrade process, and support a more consistent experience for anyone building with the SDK.
Article Discussion: