Decisões
ADR-0003 — Versões da arquitetura
- Status: aceita
- Data: 2026-10-18
- Cumpre: ORG-0001, ORG-0010
Contexto
As stacks precisam saber o que mudou na arquitetura e o que precisam fazer, cada uma no seu ritmo.
Este repositório não acompanha as stacks (ADR-0001), então a informação tem que estar na própria
versão. O design system já resolve o mesmo problema com versões marcadas e um CHANGELOG.md.
Decisão
- Versões marcadas
arquitetura-vX.Y.Z, com umCHANGELOG.mdque traz, em cada versão, a parte "Para as stacks": o que cada stack precisa fazer ao adotar a versão. - Compatibilidade:
- maior: muda uma regra (as stacks precisam agir);
- menor: acrescenta sem exigir ação (ORG que as stacks já cumprem, ADR pré-escrita nova, guia, script);
- correção: só texto.
- Cada stack guarda a versão adotada no arquivo
ARQUITETURA, na raiz. - Adotar uma versão é uma change na stack (
arquitetura-X-Y-Z), que copiadocs/decisoes/organizacao/da versão nova e segue o "Para as stacks". - As tags são criadas pelo mantenedor.
- Pré-versões levam um sufixo depois do número (
arquitetura-vX.Y.Z-dev): marcam uma versão em construção, que uma stack piloto pode usar, sem promessa de compatibilidade. - Enquanto a versão maior for 0 (
0.y.z), qualquer versão pode mudar uma regra; aarquitetura-v1.0.0só sai depois de usos reais, e a partir dela vale o item 2.
Alternativas consideradas
| Alternativa | Por que não |
|---|---|
Sem versões, a stack segue o main | Por que não: a regra muda sob os pés da stack, sem aviso nem ordem |
| Versão por data | Por que não: não diz se a mudança exige ação |
Consequências
- A stack sabe exatamente que regras e que ORGs valem para ela.
- Toda mudança aqui precisa de uma linha no
CHANGELOG.mddizendo o que as stacks fazem.