Como decidimos

Cada decisão da stack é registada como um ADR (Architecture Decision Record — registo de decisão de arquitetura) — uma página curta e datada que regista o que decidimos e, mais importante, porquê.

Formato da página

Cada página de decisão tem estas secções:

• Estado — Proposed → Accepted → (Deprecated | Superseded by ADR-XXXX)
• Contexto — as forças em jogo: requisitos, restrições, o que motivou esta decisão agora
• Opções consideradas — os candidatos realistas, com prós e contras
• Decisão — a decisão numa só linha, mais o raciocínio em poucas frases
• Consequências — o que fica mais fácil, o que fica mais difícil, aquilo de que abdicamos explicitamente

Regras do jogo

1. Uma decisão por página. Se um tema se ramificar (p. ex., a escolha da base de dados afeta a escolha do ORM), registam-se como ADR separados que apontam uns para os outros.
2. Numerados sequencialmente, com zeros à esquerda: 0001, 0002, … Os números nunca são reutilizados.
3. Datados. A data do ADR é o dia em que a decisão foi tomada.
4. As decisões Aceites só mudam na própria página para correções e alterações pontuais. Uma alteração que mantém a camada e o sentido da decisão — um facto desatualizado, um pacote ou uma definição trocados — edita-se na página, com uma nota datada a dizer o que substituiu: “(Alterado em 2026-11-12: …)”. Uma decisão diferente leva um novo ADR que substitui o anterior. As páginas antigas ficam para o histórico.
5. Âmbito de toda a empresa. Estes ADR são predefinições para todos os novos projetos. Um produto pode desviar-se, mas tem de escrever o seu próprio ADR a explicar porquê.
6. As alternativas são documentadas com honestidade. Quem cá estiver no futuro deve conseguir ver o que foi rejeitado e porquê, para não voltarmos a discutir questões resolvidas sem informação nova.

Ciclo de vida do estado

Proposed ──discutir──> Accepted ──o tempo passa──> Superseded by ADR-XXXX
                      │
                      └──> Deprecated (já não recomendado, nada o substitui por agora)

Adicionar uma nova decisão

1. Cria src/content/docs/decisions/NNNN-short-slug.md (o número seguinte), mais a sua versão em português em src/content/docs/pt/decisions/NNNN-short-slug.md.

2. Parte de um ADR existente como modelo e preenche Contexto / Opções / Decisão / Consequências.

3. Preenche o frontmatter. O cabeçalho da página, a barra lateral e a página inicial são construídos a partir dele, por isso não há nenhuma tabela para atualizar à mão, e o build falha se faltar um campo:

   title: "ADR-0018: Short layer name"
   description: One sentence with the decision.
   decision: "PostgreSQL" # a resposta curta
   band: data # app, data ou ship
   status: proposed # proposed, accepted, deprecated ou superseded
   date: 2026-10-21 # o dia em que a decisão foi tomada
   scope: "Company-wide default for all new apps"
   supersededBy: ADR-0021 # apenas quando o estado é superseded

4. Cria ligações para os ADR em que este assenta (/pt/decisions/NNNN-…/ nas páginas em português, /decisions/NNNN-…/ nas em inglês). As ligações no topo da página, “Apoia-se em” e “Citado por”, são construídas a partir delas.