Versioning scheme

Learn how Lerian approaches semantic versioning, how we manage breaking changes, and how to interpret the release candidate designations used for pre-release builds.

The versioning scheme describes how we assign and increment version numbers. It clarifies the meaning of major, minor, and patch releases, how we handle breaking changes, and the role of pre-release tags.

By following this structure, you can anticipate the impact of each update and plan migrations confidently.

Semantic versioning

---

We follow a modified semantic versioning scheme in the format X.Y.Z [-designation], where:

Version type	Increment frequency	Characteristics	Example
X (Major Version)	Evaluated every two development cycles, but only released if there are significant changes.	May introduce breaking changes. Requires explicit upgrade steps.	1.0.0 → 2.0.0
Y (Minor Version)	Every development cycle	Maintains backward compatibility. Introduces new features and functionality.	1.0.0 → 1.1.0
Z (Patch Version)	As needed, outside the regular cycle	For hotfixes, security patches, and critical updates. Maintains backward compatibility.	1.1.0 → 1.1.1

Breaking changes

---

Breaking changes are part of the natural evolution of the platform. They happen when an update alters or removes behavior in a way that is not fully compatible with previous versions.

To keep this process predictable, we follow strict rules and communicate early, allowing your teams to prepare with confidence.

• Breaking changes are introduced only in a major version.
• They are announced in advance, always with clear migration guides and practical examples.
• Deprecated features emit warnings before removal, giving teams time to adjust without sudden impact.
• We aim to minimize disruption by grouping breaking changes together and providing alternative solutions whenever possible.

Examples

• Field replacement: In v2, the chartOfAccounts field was removed and replaced by transactionRoute, routeFrom, and routeTo for better clarity and control.
• Validation rules: The environment variable ACCOUNT_TYPE_VALIDATION was introduced in v3, requiring explicit account type validation that was previously optional.
• Deprecation cycle: The scale field emitted deprecation warnings in v2 before being fully removed in v3.

Pre-release designations

---

We use the following pre-release designations when applicable:

Designation	Description	Characteristics	Example
-alpha.N	Early development builds.	Potentially unstable, not for production use. May contain incomplete features.	1.1.0-alpha.1
-beta.N	Feature-complete builds undergoing testing.	Suitable for testing environments. Feature-frozen, focusing on stability and bug fixes.	1.1.0-beta.1
-rc.N	Release Candidates.	Expected to be stable and production-ready. Only critical bug fixes applied before the final release.	1.1.0-rc.1

Examples

Potential releases

• 1.0.0 → Initial stable release
• 1.0.1 → Patch with bug fixes
• 1.1.0-alpha.1 → Alpha for next minor
• 1.1.0-beta.1 → Beta for next minor
• 1.1.0-rc.1 → Release candidate
• 1.1.0 → Stable minor release
• 1.2.0 → Next minor release
• 2.0.0 → New major version