adjustments on docs
This commit is contained in:
@@ -0,0 +1,67 @@
|
||||
# PR-013 [DEBUGGER]: Consume Structured Fault Events
|
||||
|
||||
## Briefing
|
||||
|
||||
O runtime e o host agora produzem `CrashReport` e emitem evento `fault` estruturado no protocolo do debugger. Mas o lado consumidor do DevTools ainda nao foi ajustado para tratar esse evento como dado de primeira classe. Sem isso, o debugger continua dependente de logs gerais ou de texto livre para exibir falhas da VM.
|
||||
|
||||
Esta PR fecha a ponta do debugger: faults estruturados passam a ser recebidos, armazenados e renderizados como diagnostico explicito, separado de logs e telemetria numerica.
|
||||
|
||||
## Problema
|
||||
|
||||
- o protocolo ja expõe `DebugEvent::Fault`, mas o cliente do debugger ainda pode ignorar esse evento;
|
||||
- traps, panics e falhas de init continuam sem superficie dedicada no tooling;
|
||||
- o operador do debugger nao consegue distinguir com clareza:
|
||||
- log normal;
|
||||
- violacao de certificacao;
|
||||
- fault terminal da VM.
|
||||
|
||||
## Alvo
|
||||
|
||||
- cliente do debugger / DevTools que consome `DebugEvent`
|
||||
- componentes de UI/estado que exibem logs, telemetria e status de execucao
|
||||
- testes do lado cliente do debugger, se existirem no repo
|
||||
|
||||
## Escopo
|
||||
|
||||
- Consumir `DebugEvent::Fault` como evento estruturado, nao como log generico.
|
||||
- Exibir pelo menos:
|
||||
- tipo (`vm_trap`, `vm_panic`, `vm_init`);
|
||||
- resumo;
|
||||
- `pc`, quando existir;
|
||||
- `trap_code` e `opcode`, quando existirem.
|
||||
- Manter faults historicos recentes no estado do debugger de forma simples e deterministica.
|
||||
- Garantir que um fault terminal fique visualmente distinguivel de log comum.
|
||||
|
||||
## Fora de Escopo
|
||||
|
||||
- Redesenhar toda a UI do debugger.
|
||||
- Alterar novamente o protocolo do host, salvo ajuste minimo estritamente necessario.
|
||||
- Implementar crash screen dentro da VM/firmware.
|
||||
- Introduzir persistencia em disco de faults do debugger.
|
||||
|
||||
## Abordagem
|
||||
|
||||
1. Auditar o cliente do debugger e localizar onde `DebugEvent` e desserializado e roteado.
|
||||
2. Adicionar tratamento explicito para `fault`, com estado proprio no cliente.
|
||||
3. Renderizar o fault em area dedicada ou secao claramente separada de logs.
|
||||
4. Preservar os campos estruturados; nenhuma logica deve depender de parsear `summary`.
|
||||
5. Se houver historico, limitar o buffer de faults para manter simplicidade e previsibilidade.
|
||||
|
||||
## Criterios de Aceite
|
||||
|
||||
- O debugger reconhece `DebugEvent::Fault`.
|
||||
- Um `VmTrap` aparece com `trap_code`, `opcode`, `pc` e resumo.
|
||||
- Um `VmPanic` aparece distinto de `VmTrap`, sem depender de convencao textual.
|
||||
- Um `VmInit` aparece distinto de fault de runtime.
|
||||
- O fluxo de logs continua funcionando sem regressao.
|
||||
|
||||
## Tests
|
||||
|
||||
- Teste de desserializacao/roteamento do cliente cobrindo evento `fault`.
|
||||
- Teste de estado/UI garantindo que `VmTrap` e `VmPanic` aparecem em superficie dedicada.
|
||||
- Se houver suite de frontend/cliente, rodar a suite relevante do debugger.
|
||||
- Se o cliente estiver no mesmo crate do host, incluir ao menos teste unitario do handler de eventos.
|
||||
|
||||
## Risco
|
||||
|
||||
Baixo a medio. O maior risco e introduzir uma segunda representacao local de fault que volte a colapsar semantica em texto. A implementacao deve reaproveitar o protocolo estruturado ja existente e manter a taxonomia pequena e estavel.
|
||||
+80
@@ -0,0 +1,80 @@
|
||||
# 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.
|
||||
+77
@@ -0,0 +1,77 @@
|
||||
# PR-018 [SPECS]: Reorganize Hardware Specification Surface
|
||||
|
||||
## Briefing
|
||||
|
||||
As specs de hardware e sistema acumuladas no repositorio contem material valioso, mas a organizacao atual esta irregular. Hoje convivem no mesmo pacote temas de perifericos, VM, firmware, cartridge, assets e host ABI, com pesos muito diferentes entre si e sem uma separacao suficientemente clara entre conteudo normativo e conteudo pedagogico.
|
||||
|
||||
Esta PR nao pretende reescrever toda a especificacao. Ela existe para organizar a superficie documental, definir taxonomia e preparar o terreno para futuras PRs de conteudo sem perpetuar a colcha de retalhos atual.
|
||||
|
||||
## Problema
|
||||
|
||||
- o pacote de specs atual mistura dominios heterogeneos sob a mesma superficie de "hardware";
|
||||
- ha capitulos extensos e narrativos convivendo com material que deveria ser normativo;
|
||||
- ownership documental por area nao esta claro;
|
||||
- a navegacao esta fraca para quem precisa alterar apenas um dominio tecnico;
|
||||
- o risco de contradicao entre spec, arquitetura e implementacao cresce a cada novo remendo.
|
||||
|
||||
## Alvo
|
||||
|
||||
- `docs/specs/hardware/` e sua organizacao atual;
|
||||
- relacao entre specs de hardware, arquitetura de runtime, firmware, cartridge, assets e host ABI;
|
||||
- indice e taxonomia documental das specs tecnicas.
|
||||
|
||||
## Escopo
|
||||
|
||||
- Definir uma taxonomia clara para as specs tecnicas do projeto, por exemplo:
|
||||
- machine/runtime;
|
||||
- hardware/peripherals;
|
||||
- firmware/system;
|
||||
- cartridge/package;
|
||||
- host ABI;
|
||||
- assets/tooling.
|
||||
- Decidir o que realmente pertence ao pacote de "hardware" e o que deve migrar para outra categoria.
|
||||
- Propor uma nova arvore de organizacao e navegacao para as specs.
|
||||
- Mapear os capitulos atuais para seus destinos futuros.
|
||||
- Explicitar o que e:
|
||||
- normativo;
|
||||
- explicativo;
|
||||
- historico;
|
||||
- pedagogico.
|
||||
|
||||
## Fora de Escopo
|
||||
|
||||
- Reescrever tecnicamente todos os capitulos.
|
||||
- Atualizar o conteudo detalhado de cada spec nesta mesma PR.
|
||||
- Alterar a arquitetura do runtime por meio de reorganizacao documental.
|
||||
- Normalizar todo estilo editorial do repositorio.
|
||||
|
||||
## Abordagem
|
||||
|
||||
1. Inventariar a estrutura atual das specs e classificar cada documento por dominio e funcao.
|
||||
2. Definir uma taxonomia pequena, defensavel e duravel para as specs do projeto.
|
||||
3. Desenhar a arvore alvo de diretorios e indices.
|
||||
4. Mapear capitulo atual -> destino futuro, explicitando:
|
||||
- permanece;
|
||||
- move;
|
||||
- divide;
|
||||
- funde;
|
||||
- vira historico.
|
||||
5. Ajustar a navegacao minima para que a reorganizacao nao deixe o leitor sem trilha.
|
||||
|
||||
## Criterios de Aceite
|
||||
|
||||
- Existe uma taxonomia aprovada para as specs tecnicas.
|
||||
- A organizacao alvo de diretorios e indices esta definida.
|
||||
- Cada capitulo atual relevante tem destino planejado.
|
||||
- A separacao entre conteudo normativo e pedagogico fica explicita.
|
||||
- O pacote de "hardware" deixa de ser deposito generico de temas nao relacionados.
|
||||
|
||||
## Tests
|
||||
|
||||
- Revisao manual da navegacao entre indice principal, README das specs e topicos afetados.
|
||||
- Confirmacao de que a nova organizacao nao cria links quebrados nos pontos principais do repositorio.
|
||||
- Validacao de que a taxonomia proposta e coerente com o documento canonico de arquitetura.
|
||||
|
||||
## Risco
|
||||
|
||||
Medio. O risco principal e trocar a desordem atual por uma reorganizacao cosmetica sem criterio de autoridade nem ownership. A PR deve sair com taxonomia clara e mapa de migracao; sem isso, sera apenas renomeacao de pastas.
|
||||
@@ -0,0 +1,35 @@
|
||||
# Pull Requests
|
||||
|
||||
Este diretório armazena propostas de PRs arquiteturais e de implementação para o runtime.
|
||||
|
||||
## Padrão
|
||||
|
||||
Toda PR neste diretório deve ser autocontida.
|
||||
|
||||
Cada documento deve incluir, no mínimo:
|
||||
|
||||
- `Briefing`
|
||||
- `Alvo`
|
||||
- `Critérios de Aceite`
|
||||
- `Tests`, quando necessário
|
||||
|
||||
## Barra de Qualidade
|
||||
|
||||
O padrão esperado é JVM-grade.
|
||||
|
||||
Isso implica:
|
||||
|
||||
- arquitetura vem antes de implementação;
|
||||
- decisões arquiteturais não devem ser tomadas durante a fase de implementação;
|
||||
- quando a implementação encontrar dúvida arquitetural, a PR deve voltar para discussão de arquitetura;
|
||||
- diante de ambiguidade estrutural, é preferível interromper a execução da PR e levantar um questionamento severo do que cristalizar uma decisão errada no código.
|
||||
|
||||
## Condução
|
||||
|
||||
Uma PR deste diretório deve:
|
||||
|
||||
- definir claramente o problema;
|
||||
- delimitar o alvo da mudança;
|
||||
- explicitar o que está fora de escopo quando houver risco de expansão;
|
||||
- estabelecer critérios objetivos de aceite;
|
||||
- definir a estratégia de teste proporcional ao risco da mudança.
|
||||
Reference in New Issue
Block a user