> ## 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**.  <br /><br />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**.  <br /><br /> 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**.  <br /><br /> 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. O campo `route` continua aceito para compatibilidade retroativa, mas não controla mais a validação.
* **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**.  <br /><br /> Pode conter funcionalidades incompletas.                       | *1.1.0-alpha.1* |
| **-beta.N**  | Builds com funcionalidades completas em fase de testes. | **Adequado para ambientes de teste.** <br /><br /> 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**.  <br /><br /> 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