adjustments on docs
This commit is contained in:
-80
@@ -1,80 +0,0 @@
|
||||
# PR-017 [ARCHITECTURE]: Establish Single Canonical Runtime Architecture
|
||||
|
||||
## Briefing
|
||||
|
||||
O runtime hoje tem mais de um documento tentando orientar a arquitetura, com niveis diferentes de autoridade e maturidade. Na pratica, isso cria um problema de governanca tecnica: contribuidores podem consultar documentos distintos, chegar a conclusoes diferentes e ainda assim parecer "alinhados com a arquitetura".
|
||||
|
||||
Esta PR fecha essa ambiguidade. O objetivo nao e produzir mais texto, e sim definir um unico documento canonico de arquitetura do runtime e rebaixar, fundir ou remover o que hoje compete com ele.
|
||||
|
||||
## Problema
|
||||
|
||||
- ha mais de um documento arquitetural relevante no repositorio;
|
||||
- pelo menos um deles ainda se apresenta como `stub`, enquanto outro se declara baseline autoritativo;
|
||||
- a fronteira entre:
|
||||
- arquitetura normativa;
|
||||
- roadmap;
|
||||
- documento de apoio;
|
||||
- material pedagogico;
|
||||
nao esta explicitamente fechada;
|
||||
- sem um documento canonico, a arquitetura deixa de ser guardrail e vira opiniao distribuida.
|
||||
|
||||
## Alvo
|
||||
|
||||
- documentos arquiteturais do runtime no raiz e em `docs/`;
|
||||
- definicao de autoridade documental para runtime/VM/ABI/scheduler/GC/verifier;
|
||||
- governanca minima para futuras PRs arquiteturais.
|
||||
- todo conteudo em ingles.
|
||||
-
|
||||
|
||||
## Escopo
|
||||
|
||||
- Escolher um unico documento canonico para a arquitetura do runtime.
|
||||
- Definir o papel explicito dos demais documentos relacionados:
|
||||
- canonico;
|
||||
- derivado;
|
||||
- historico;
|
||||
- roadmap;
|
||||
- pedagogico.
|
||||
- Consolidar ou remover o documento `stub` que hoje compete com o baseline.
|
||||
- Garantir que as invariantes arquiteturais centrais tenham um unico lar.
|
||||
- Registrar a regra de manutencao: mudanca arquitetural exige atualizacao do documento canonico no mesmo PR.
|
||||
|
||||
## Fora de Escopo
|
||||
|
||||
- Reorganizar todo o diretorio `docs/`.
|
||||
- Reescrever todas as specs detalhadas do projeto.
|
||||
- Revisar estilo textual de todo material pedagogico.
|
||||
- Introduzir mudancas comportamentais na VM, runtime ou firmware.
|
||||
|
||||
## Abordagem
|
||||
|
||||
1. Inventariar os documentos que hoje falam pela arquitetura do runtime.
|
||||
2. Definir uma taxonomia minima de documentos para o repositorio:
|
||||
- normativo;
|
||||
- especificacao;
|
||||
- roadmap;
|
||||
- historico;
|
||||
- pedagogico.
|
||||
3. Escolher o documento canonico e migrar para ele apenas as invariantes que realmente governam o sistema.
|
||||
4. Rebaixar, fundir ou remover o documento `stub` e qualquer outro texto que gere concorrencia de autoridade.
|
||||
5. Deixar links e notas de transicao claros para evitar pontos cegos.
|
||||
|
||||
## Criterios de Aceite
|
||||
|
||||
- Existe exatamente um documento canonico de arquitetura do runtime.
|
||||
- O papel dos demais documentos arquiteturais esta explicito.
|
||||
- O documento `stub` deixa de competir por autoridade:
|
||||
- removido; ou
|
||||
- convertido em indice/redirecionamento sem ambiguidade.
|
||||
- As invariantes centrais do runtime ficam localizadas no documento canonico.
|
||||
- Fica documentada a regra de que PR arquitetural deve atualizar o documento canonico quando alterar invariantes.
|
||||
|
||||
## Tests
|
||||
|
||||
- Revisao estrutural dos links e referencias entre documentos afetados.
|
||||
- Confirmacao manual de que nao restaram dois documentos com claims conflitantes de autoridade.
|
||||
- Se a PR mover ou renomear arquivos, validar que referencias internas em `README`, `ARCHITECTURE` e `docs/` continuam corretas.
|
||||
|
||||
## Risco
|
||||
|
||||
Medio. O risco principal e produzir consolidacao superficial, deixando ambiguidade semantica mesmo depois da reorganizacao. A PR deve ser severa: se dois documentos ainda puderem ser lidos como "fonte final", a mudanca falhou.
|
||||
Reference in New Issue
Block a user