Web Analytics Made Easy - Statcounter
Skip to content

Versioning#

Versioning matters in SAMSON because an extension is built against a specific SDK release and then loaded into a specific SAMSON runtime.

This page focuses on the developer-facing side of versioning: compatibility, upgrade strategy, and extension release numbers. For the end-user explanation, see the User guide: Versioning.

See also

SBCContainerVersionNumber

Two version numbers matter#

As an extension developer, you usually care about two independent version lines:

  • the SAMSON / SDK version you build against
  • your own extension version that users see in releases

These serve different purposes.

The SDK version controls whether the extension is compatible with a given SAMSON runtime. The extension version tells users and the marketplace which release of your extension is newer.

SAMSON and SDK semantic versioning#

SAMSON and the SDK follow a semantic versioning scheme based on major.minor.patch.

The practical rule is:

  • incompatible platform changes increment the major version
  • backward-compatible feature additions increment the minor version
  • backward-compatible fixes increment the patch version

That policy is what makes compatibility decisions possible at startup.

Compatibility of SAMSON Extensions#

When SAMSON starts, it checks the SDK version that was used to build each extension and decides whether that version is compatible with the running SAMSON version.

The key compatibility rule is:

  • the major versions must match
  • the SDK minor version must not be newer than the SAMSON minor version

Example:

  • an extension built with SDK 1.5.2 can load in SAMSON 1.7.8
  • an extension built with SDK 1.8.5 cannot load in SAMSON 1.7.8

This protects users from loading extensions that may depend on newer API functionality than their SAMSON build provides.

Extension version numbers#

Independent of the SDK version, each extension has its own major.minor.patch version number.

Use that extension version to communicate your own releases:

  • breaking changes
  • new features
  • fixes

SAMSON does not enforce a strict policy for how you increment the extension version beyond the major.minor.patch format, but you should still follow a consistent scheme. The most useful choice is usually normal semantic versioning.

Automatic updates#

SAMSON can automatically update installed extensions when a newer compatible version becomes available on SAMSON Connect.

That means:

  • publishing a newer extension version is not enough by itself
  • the uploaded build must also target an SDK version compatible with the user's SAMSON installation

If you publish only a build for a newer incompatible major SDK version, users on older SAMSON releases will not receive that update.

Practical release advice#

  • Update the SDK regularly if you want access to new APIs and fixes.
  • Increase the extension version when you publish a new marketplace release.
  • Be deliberate when raising your minimum supported SAMSON/SDK baseline, because that changes who can install or auto-update the extension.