> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Versioning scheme

> Learn how Lerian applies semantic versioning, how we manage breaking changes, and how to interpret 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.

## 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**.  <br /><br />Requires explicit upgrade steps.                         | *1.0.0 → 2.0.0* |
| **Y (Minor Version)** | Every development cycle                                                                         | **Maintains backward compatibility**.  <br /><br /> 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**.  <br /><br /> Maintains backward compatibility. | *1.1.0 → 1.1.1* |

## Breaking changes

***

A breaking change happens 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.

* We introduce breaking changes **only in a major version**.
* They are **announced in advance**, always with migration guides and examples.
* Deprecated features **emit warnings** before removal, so teams have time to adjust.
* We aim to **minimize disruption** by grouping breaking changes together and providing alternative solutions whenever possible.

### Examples

* **Field replacement**: `routeId` (UUID) superseded the free-text `route` field in transaction payloads. The `route` field remains accepted for backward compatibility but no longer drives validation.
* **Validation rules**: The Ledger Settings API replaced the `ACCOUNT_TYPE_VALIDATION` and `TRANSACTION_ROUTE_VALIDATION` environment variables. The API controls accounting validation per ledger without redeployment.
* **Deprecation cycle**: We removed the `scale` field from transaction amounts in v3, when amount handling moved to a numeric system.

## 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**.  <br /><br /> May contain incomplete features.                        | *1.1.0-alpha.1* |
| **-beta.N**  | Feature-complete builds undergoing testing. | **Suitable for testing environments.** <br /><br /> Feature-frozen, focusing on stability and bug fixes.                | *1.1.0-beta.1*  |
| **-rc.N**    | Release Candidates.                         | **Expected to be stable and production-ready**.  <br /><br /> 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