Transitioning the JavaScript SDK to Semantic Versioning

Background

Versioning is critical in software development, ensuring developers can confidently manage dependencies and compatibility. Historically, the CrafterCMS JavaScript SDK (JS-SDK) has been versioned alongside the core CrafterCMS platform, which does not follow semantic versioning (SemVer). While this alignment helped track product releases, it introduced challenges for UI tools and package managers that expect strict SemVer compliance. To address this, we are transitioning the JS-SDK to an independent semantic versioning scheme.

Why the Change?

Many UI tools, frameworks, and package managers rely on SemVer to determine compatibility and resolve dependencies correctly. Because CrafterCMS itself does not follow SemVer, the previous approach caused inconsistencies and unnecessary upgrades. By decoupling the JS-SDK from the core product's versioning and adopting SemVer, we aim to:

• Improve compatibility with JavaScript package managers and UI tooling.

• Allow independent JS-SDK improvements without unnecessary major version bumps.

• Provide a predictable and structured upgrade path for developers.

New Versioning Scheme

Starting from JS-SDK version 4.3.0, the CrafterCMS JS-SDK will now follow the standard semantic versioning format:

MAJOR.MINOR.PATCH

How It Works

• Major (MAJOR): Significant updates that introduce breaking changes.

• Minor (MINOR): Backward-compatible feature updates and improvements.

• Patch (PATCH): Backward-compatible bug fixes and maintenance releases.

For example:

• The latest SDK release, 4.3.0, will remain 4.3.0, following SemVer going forward.

• If a breaking change occurs in the JS-SDK, the next version would be 5.0.0.

• If a minor feature update is introduced, the next version would be 4.4.0.

• If a bug fix is applied, the next version would be 4.3.1.

Benefits of This Approach

This approach allows us to maintain compatibility with SemVer while ensuring logical and structured version increments within CrafterCMS's evolving ecosystem. The benefits include:

• Clear and structured version increments for package managers.

• Easier dependency management for developers using the JS-SDK.

• Decoupled release cycle from the main product, enabling faster JS-SDK iteration.

What to Expect Next?

The new versioning scheme will be implemented in the next release. Developers using the JS-SDK should continue to follow standard package manager upgrade guidelines. We will also update our documentation to reflect these changes.

We welcome feedback from our community to ensure a smooth transition. If you have questions, feel free to reach out on our community Slack..