> ## 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.

# Esquema de versionamento

> Saiba como a Lerian aplica o versionamento semântico, como gerenciamos breaking changes e como interpretar as designações de release candidate usadas em builds de pré-release.

O esquema de versionamento descreve como atribuímos e incrementamos os números de versão. Ele esclarece o significado dos releases principais, secundários e de patch, como tratamos breaking changes e o papel das tags de pré-release.

## Versionamento semântico

***

Seguimos um esquema de **versionamento semântico modificado** no formato **X.Y.Z \[-designação]**, onde:

| Tipo de versão | Frequência de incremento | Características | Exemplo |
| - | - | - | - |
| **X (Versão Principal)** | Avaliada a cada dois ciclos de desenvolvimento, mas **apenas lançada se houver mudanças significativas**. | **Pode introduzir breaking changes**.   Exige etapas explícitas de upgrade. | *1.0.0 → 2.0.0* |
| **Y (Versão Secundária)** | A cada ciclo de desenvolvimento | **Mantém compatibilidade retroativa**.    Introduz novas funcionalidades e recursos. | *1.0.0 → 1.1.0* |
| **Z (Versão de Patch)** | Conforme necessário, fora do ciclo regular | **Para hotfixes, patches de segurança e atualizações críticas**.    Mantém compatibilidade retroativa. | *1.1.0 → 1.1.1* |

## Breaking changes

***

Um breaking change ocorre quando uma atualização altera ou remove um comportamento de um jeito que não é totalmente compatível com versões anteriores.

Para manter esse processo previsível, seguimos regras rígidas e comunicamos com antecedência.

* Introduzimos breaking changes **apenas em uma versão principal**.
* Eles são **anunciados com antecedência**, sempre com guias de migração e exemplos.
* Funcionalidades descontinuadas **emitem avisos** antes da remoção, para que as equipes tenham tempo de se adaptar.
* Buscamos **minimizar as interrupções** agrupando breaking changes e oferecendo soluções alternativas sempre que possível.

### Exemplos

* **Substituição de campo**: o `routeId` (UUID) substituiu o campo de texto livre `route` nos payloads de transação. A v1 ainda aceita `route` quando `routeId` está ausente. A v2 aceita apenas `routeId`.
* **Regras de validação**: a API Ledger Settings substituiu as variáveis de ambiente `ACCOUNT_TYPE_VALIDATION` e `TRANSACTION_ROUTE_VALIDATION`. A API controla a validação contábil por ledger sem novo deploy.
* **Ciclo de descontinuação**: removemos o campo `scale` dos valores de transação na v3, quando o tratamento de valores passou para um sistema numérico.

## Designações de pré-release

***

Usamos as seguintes designações de pré-release **quando aplicável**:

| Designação | Descrição | Características | Exemplo |
| :- | :- | :- | :- |
| **-alpha.N** | Builds de desenvolvimento inicial. | **Potencialmente instável, não indicado para uso em produção**.    Pode conter funcionalidades incompletas. | *1.1.0-alpha.1* |
| **-beta.N** | Builds com funcionalidades completas em fase de testes. | **Adequado para ambientes de teste.**   Com funcionalidades congeladas, focado em estabilidade e correções de bugs. | *1.1.0-beta.1* |
| **-rc.N** | Release Candidates. | **Espera-se que seja estável e pronto para produção**.    Apenas correções críticas de bugs são aplicadas antes do release final. | *1.1.0-rc.1* |

### Exemplos

**Possíveis releases**

* *1.0.0* → Release estável inicial
* *1.0.1* → Patch com correções de bugs
* *1.1.0-alpha.1* → Alpha para a próxima versão secundária
* *1.1.0-beta.1* → Beta para a próxima versão secundária
* *1.1.0-rc.1* → Release candidate
* *1.1.0* → Release secundário estável
* *1.2.0* → Próximo release secundário
* *2.0.0* → Nova versão principal


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.