Semantic Versioning

Semantic Versioning is the versioning strategy used for all Business Systems within the Innopo Modular Systems Framework (IMSF). It provides a clear, predictable way to understand how a system has changed, what level of risk an update carries, and how platforms can safely evolve over time.

Each Business System follows the format MAJOR.MINOR.PATCH, for example: 1.4.2. This structure communicates whether changes are backwards-compatible or whether they introduce breaking changes that require migration.

Version format

Every system version uses the same three-part structure:

MAJOR.MINOR.PATCH

• MAJOR – incompatible API or behaviour changes that may break existing platforms if adopted without migration.
• MINOR – backwards-compatible additions, such as new features, configuration options, or improvements.
• PATCH – backwards-compatible bug fixes and small, low-risk adjustments.

This structure gives a quick indication of the impact of a change, before reading any detailed documentation.

How versions are used in Innopo

Each Business System in the Systems Library has its own version history. Platforms do not use “latest” by default; they are explicitly pinned to specific versions of each system. This ensures that behaviour remains stable and identical between environments.

Key rules:

• Every system is assigned a semantic version before being used in a project.
• Projects store a mapping of which systems they use and which versions they are pinned to.
• New versions do not automatically apply to existing projects.
• Upgrading systems is an intentional decision, not a background process.

Patch versions

Patch releases address small, backward-compatible changes such as bug fixes, minor UX improvements, performance tweaks, or internal refactoring that does not affect public behaviour.

Examples of patch changes:

• Fixing a validation bug in a form.
• Improving error messages without changing logic.
• Small visual adjustments that do not affect layout structure.
• Internal code clean-up that doesn’t alter system behaviour.

Patch updates are the lowest risk and can usually be adopted with minimal testing, though they are still optional for each project.

Minor versions

Minor releases introduce new features and improvements that remain backwards-compatible. Existing functionality should continue to work without requiring changes to custom workflow logic.

Examples of minor changes:

• Adding a new optional configuration option.
• Introducing a new report or view that does not replace existing ones.
• Supporting an additional field or filter while keeping existing APIs intact.
• Extending automation rules with additional optional triggers.

Minor updates can offer meaningful benefits, but they are still optional. Projects may choose to adopt them when the improvements are relevant to their use case.

Major versions

Major releases include breaking changes. These may alter behaviour, remove deprecated features, or restructure parts of the system in ways that require migrations or adjustments to custom workflow logic.

Examples of major changes:

• Changing core data structures in a way that is not backwards-compatible.
• Removing previously supported configuration options or APIs.
• Redesigning core flows that partners may depend on.
• Modifying how states or transitions are represented in the system.

Major updates are always opt-in. They require planning, migration steps, and explicit agreement before adoption in any project.

Pinning systems to versions

For each project, the systems it uses and the versions they are pinned to are tracked explicitly. This ensures that:

• The platform behaves consistently across development and production.
• Future system updates do not alter behaviour unless intentionally applied.
• Upgrades can be tested in isolation before being rolled out to live environments.

The Innopo Platform maintains a record such as:

• auth-system – 1.0.3
• onboarding-system – 0.4.1
• quote-engine – 0.9.0
• notifications-system – 0.2.5

This mapping forms part of the platform’s technical snapshot at any given time.

Changelogs and migration notes

Each system version is accompanied by a concise record of what has changed. For non-breaking changes, this is primarily descriptive. For breaking changes, migration notes are provided.

Each release includes:

• A summary of changes.
• A categorisation (patch, minor, major).
• Notes about behavioural differences, if any.
• For major versions: migration steps and upgrade considerations.

This documentation allows informed decisions about when and how to adopt new versions.

Deprecation and legacy support

Over time, older versions of systems may be deprecated. Deprecation means a version is still supported but no longer actively enhanced, and may be scheduled for end-of-life.

Deprecation practices:

• Marking older versions as deprecated in the Innopo Platform.
• Communicating suggested upgrade paths.
• Maintaining stability for existing projects until upgrades are agreed.
• Defining a clear end-of-life date where necessary.

This approach ensures projects have time to plan migrations without unexpected disruption.

How this affects partners

For partners, Semantic Versioning provides transparency and control. They can see which systems power their platform and what versions are in use, as well as which updates are available.

Partner benefits:

• Clarity over what is running in production.
• Confidence that behaviour will not change unexpectedly.
• Visibility into upcoming improvements and changes.
• Ability to choose when to schedule upgrades.

Summary

Semantic Versioning is the backbone of how systems evolve inside Innopo. By following the MAJOR.MINOR.PATCH model, pinning system versions per project, and documenting every change, Innopo creates a predictable, transparent upgrade path. This makes it possible to keep platforms stable in the present while still enabling continuous improvement over time.