# Estratégia de Versionamento — Mud Sentinel

**Documento:** `engenharia/04-versionamento.md`  
**Versão:** 1.0.0  
**Status:** Vigente

---

## 1. Versionamento de produto

Adotar **Semantic Versioning 2.0.0** para releases da plataforma:

```text
MAJOR.MINOR.PATCH[-prerelease]
```

| Parte | Quando incrementa |
|-------|-------------------|
| MAJOR | Breaking change em API pública ou comportamento contratado |
| MINOR | Nova capacidade compatível |
| PATCH | Correções compatíveis |

**Justificativa:** previsibilidade para clientes enterprise e consumidores de API.

---

## 2. API HTTP

- Prefixo `/api/v1`.
- Breaking changes → `/api/v2` com período de depreciação ≥ 90 dias (exceto vulnerabilidade crítica).
- Changelog de API em `docs/api/CHANGELOG.md` (quando a pasta existir).
- OpenAPI publicado por versão.

Campos novos additive são MINOR; remoção/renomeação/alteração de sentido são MAJOR.

---

## 3. Eventos de integração

- Sufixo `.v1`, `.v2` no `event_type`.
- Consumidores devem ignorar campos desconhecidos (forward compatibility).
- Producers não removem campos sem nova versão.

---

## 4. Conectores de ingestão

Cada conector declara `CONNECTOR_VERSION` semver independente.  
Mudança de schema de saída → major do conector + migração de normalizer.

---

## 5. Modelos e prompts de IA

Versionar:

- `prompt_template_id` + `version`
- `model_name` + `provider` + checksum de parâmetros relevantes
- dataset de eval associado

**Justificativa:** reproducibilidade e auditoria de recomendações.

---

## 6. Schemas de dados / migrações

- Migrações linearmente ordenadas.
- Nunca editar migration já aplicada em produção.
- Expand/contract para mudanças breaking em schema.

---

## 7. Containers e IaC

- Imagens imutáveis por digest/gitsha.
- Terraform modules versionados; upgrades via PR.
- Ambientes pinados a versões conhecidas.

---

## 8. Documentação

Docs fundacionais usam versão própria no header.  
Breaking doc de arquitetura (ex.: troca de stack Core) → MAJOR do doc + ADR.

---

## 9. Deprecação

1. Anúncio (changelog + header `Deprecation` quando aplicável).
2. Métrica de uso do endpoint/evento antigo.
3. Remoção após janela e comunicação aos tenants afetados.

---

## 10. Tags Git

- `vX.Y.Z` apenas de main/release branch.
- Notas de release automáticas a partir de Conventional Commits.