add PRs
This commit is contained in:
parent
01c50f0b20
commit
f77b9f762f
SSH Key Fingerprint:
SHA256:Z7dgqoglWwoK6j6u4QC87OveEq74WOhFN+gitsxtkf8
@ -19,6 +19,35 @@ As agendas atuais são:
|
||||
- `007-single-canonical-architecture.md`
|
||||
- `008-hardware-specs-reorganization.md`
|
||||
|
||||
## Sequenciamento Recomendado
|
||||
|
||||
Ordem sugerida para discussão e futura execução:
|
||||
|
||||
1. `007-single-canonical-architecture.md`
|
||||
2. `008-hardware-specs-reorganization.md`
|
||||
3. `006-break-monolith-runtime.md`
|
||||
4. `003-structured-runtime-abi.md`
|
||||
5. `004-syscall-fault-classification.md`
|
||||
6. `005-runtime-edge-test-plan.md`
|
||||
7. `001-system-run-cart.md`
|
||||
8. `002-packed-cartridge-loader-pmc.md`
|
||||
|
||||
Justificativa curta:
|
||||
|
||||
- `007` vem primeiro porque elimina ambiguidade sobre qual documento manda.
|
||||
- `008` vem em seguida porque reorganiza o terreno documental onde specs e arquitetura se apoiam.
|
||||
- `006` entra depois porque refactor estrutural grande sem documentação estável tende a cristalizar decisões erradas.
|
||||
- `003` e `004` formam o núcleo de contrato da borda do runtime.
|
||||
- `005` fecha a barra de qualidade antes das implementações mais arriscadas.
|
||||
- `001` e `002` dependem mais fortemente de contrato de sistema, ABI e documentação estáveis.
|
||||
|
||||
Dependências principais:
|
||||
|
||||
- `008` depende de `007`
|
||||
- `006` depende de `007`
|
||||
- `001` depende de `007`, `003`, `004` e `005`
|
||||
- `002` depende de `007` e deve ser alinhada com a reorganização documental de `008`
|
||||
|
||||
Regra de uso:
|
||||
|
||||
- se a implementação exigir decisão estrutural, ela deve nascer daqui antes de virar PR de código;
|
||||
|
||||
@ -1,57 +0,0 @@
|
||||
# PR-014 [QUALITY]: Stabilize Workspace Formatting
|
||||
|
||||
## Briefing
|
||||
|
||||
O workspace ja tem uma trilha clara de qualidade com `fmt-check`, `clippy` e `test` no fluxo de CI. Hoje, porem, a barra minima de formatacao nao esta fechando: `cargo fmt -- --check` falha por divergencias de ordenacao de imports e estilo em arquivos ja versionados.
|
||||
|
||||
Esta PR trata esse problema como higiene de base. O objetivo nao e "embelezar codigo", e sim restaurar o contrato de estilo para que a arvore volte a ter um estado formatado, previsivel e mecanico.
|
||||
|
||||
## Problema
|
||||
|
||||
- `cargo fmt -- --check` falha no estado atual do workspace;
|
||||
- ha arquivos versionados que divergem do estilo canonical do `rustfmt`;
|
||||
- enquanto isso existir, o target `ci` deixa de ser confiavel como gate minimo de merge;
|
||||
- a equipe perde sinal: falhas de estilo misturam ruido de higiene com problemas reais de implementacao.
|
||||
|
||||
## Alvo
|
||||
|
||||
- workspace Rust inteiro;
|
||||
- arquivos tocados pelo `rustfmt` que hoje geram diff;
|
||||
- fluxo `fmt-check` definido no `Makefile`.
|
||||
|
||||
## Escopo
|
||||
|
||||
- Rodar `cargo fmt` no workspace e revisar o diff gerado.
|
||||
- Confirmar que as mudancas sao estritamente de formatacao, sem alteracao semantica.
|
||||
- Restaurar `cargo fmt -- --check` para estado verde.
|
||||
- Se necessario, ajustar qualquer arquivo novo ou recente que tenha escapado do padrao.
|
||||
|
||||
## Fora de Escopo
|
||||
|
||||
- Refatorar APIs.
|
||||
- Renomear modulos.
|
||||
- Resolver warnings de `clippy`.
|
||||
- Alterar comportamento de testes ou runtime.
|
||||
|
||||
## Abordagem
|
||||
|
||||
1. Identificar exatamente quais arquivos fazem `fmt-check` falhar.
|
||||
2. Aplicar `cargo fmt` no workspace.
|
||||
3. Revisar diff para garantir ausencia de mudanca comportamental.
|
||||
4. Revalidar com `cargo fmt -- --check`.
|
||||
|
||||
## Criterios de Aceite
|
||||
|
||||
- `cargo fmt -- --check` passa no workspace.
|
||||
- O diff da PR e apenas de formatacao.
|
||||
- Nenhuma logica, assinatura publica ou comportamento de teste muda por causa desta PR.
|
||||
- O target `fmt-check` do `Makefile` volta a ser um gate confiavel.
|
||||
|
||||
## Tests
|
||||
|
||||
- Rodar `cargo fmt -- --check`.
|
||||
- Rodar ao menos `cargo test --workspace --all-targets --all-features --no-fail-fast` se a PR tocar arquivos em crates com testes relevantes, apenas para confirmar ausencia de regressao acidental.
|
||||
|
||||
## Risco
|
||||
|
||||
Baixo. O risco principal e misturar formatacao com mudanca semantica no mesmo diff. A revisao deve ser severa: qualquer alteracao nao mecanica deve sair desta PR.
|
||||
@ -1,68 +0,0 @@
|
||||
# PR-015 [QUALITY]: Burn Down Clippy Warnings
|
||||
|
||||
## Briefing
|
||||
|
||||
O workspace compila e a suite principal de testes esta saudavel, mas `cargo clippy --workspace --all-features` ainda retorna uma quantidade relevante de warnings. Isso nao e detalhe cosmetico: warnings recorrentes enfraquecem o valor do lint e escondem sinais novos que deveriam chamar atencao imediata.
|
||||
|
||||
Esta PR fecha a divida de lint com foco em warnings claros, mecanicos e de baixo risco. A meta e tornar `clippy` um gate com alta relacao sinal/ruido.
|
||||
|
||||
## Problema
|
||||
|
||||
- `cargo clippy --workspace --all-features` termina com warnings em multiplas crates;
|
||||
- ha uma mistura de problemas triviais e repetitivos:
|
||||
- `new_without_default`;
|
||||
- `collapsible_if`;
|
||||
- `redundant_closure`;
|
||||
- `clone_on_copy`;
|
||||
- `needless_borrow`;
|
||||
- `unnecessary_cast`;
|
||||
- `too_many_arguments`;
|
||||
- `module_inception`;
|
||||
- enquanto o baseline permanecer ruidoso, novos warnings entram sem friccao.
|
||||
|
||||
## Alvo
|
||||
|
||||
- crates do workspace que hoje emitem warnings de `clippy`;
|
||||
- principalmente `prometeu-vm`, `prometeu-system`, `prometeu-host-desktop-winit`, `prometeu-drivers` e `pbxgen-stress`.
|
||||
|
||||
## Escopo
|
||||
|
||||
- Eliminar warnings de `clippy` que tenham correcao local, objetiva e de baixo risco.
|
||||
- Introduzir `Default` onde a recomendacao fizer sentido sem distorcer o modelo de construcao.
|
||||
- Simplificar fluxo de controle e remocoes de ruido sintatico.
|
||||
- Decidir explicitamente o tratamento de warnings que indiquem tradeoff arquitetural real.
|
||||
|
||||
## Fora de Escopo
|
||||
|
||||
- Grandes refactors de design apenas para satisfazer lint.
|
||||
- Mudancas arquiteturais em API publica sem discussao previa.
|
||||
- Reescrever modulos inteiros por motivos esteticos.
|
||||
- Alterar a taxonomia arquitetural do runtime.
|
||||
|
||||
## Abordagem
|
||||
|
||||
1. Classificar warnings em dois grupos:
|
||||
- mecanicos e sem risco;
|
||||
- warnings que tocam modelagem publica ou ergonomia de API.
|
||||
2. Corrigir primeiro o grupo mecanico.
|
||||
3. Para warnings que implicarem decisao de design, escolher uma de duas saidas:
|
||||
- corrigir com justificativa clara;
|
||||
- silenciar localmente com comentario curto e motivo tecnico defensavel.
|
||||
4. Reexecutar `cargo clippy --workspace --all-features` ate baseline limpo ou explicitamente justificado.
|
||||
|
||||
## Criterios de Aceite
|
||||
|
||||
- `cargo clippy --workspace --all-features` termina sem warnings, ou com excecoes locais raras e justificadas no codigo.
|
||||
- Nenhuma mudanca amplia API ou comportamento sem necessidade.
|
||||
- O resultado final aumenta, e nao reduz, a legibilidade do codigo.
|
||||
- Warnings mecanicos recorrentes deixam de existir no baseline.
|
||||
|
||||
## Tests
|
||||
|
||||
- Rodar `cargo clippy --workspace --all-features`.
|
||||
- Rodar `cargo test --workspace --all-targets --all-features --no-fail-fast`.
|
||||
- Se alguma correcao tocar caminho quente do runtime, rodar tambem os testes da crate afetada de forma isolada para facilitar triagem.
|
||||
|
||||
## Risco
|
||||
|
||||
Medio. O risco nao esta no `clippy`; esta em usar o lint como desculpa para refatorar demais. Esta PR deve ser conservadora: eliminar ruido sem inventar arquitetura nova.
|
||||
@ -1,66 +0,0 @@
|
||||
# PR-016 [CI]: Separate Network-Dependent Debugger Tests
|
||||
|
||||
## Briefing
|
||||
|
||||
Os testes do host debugger passam quando executados em ambiente com permissao normal de socket, mas falham em contexto sandboxado que bloqueia bind de porta TCP. Isso cria um problema de engenharia: a suite parece instavel quando, na pratica, o comportamento observado e uma restricao do ambiente, nao um bug do runtime.
|
||||
|
||||
Esta PR organiza esses testes para que continuem existindo, continuem sendo exigidos, mas sejam executados na pista correta.
|
||||
|
||||
## Problema
|
||||
|
||||
- testes de debugger que dependem de abrir porta TCP falham em ambientes com restricao de bind;
|
||||
- o comando de workspace pode acusar falso negativo quando rodado em sandbox local;
|
||||
- sem separacao de trilha, fica dificil distinguir:
|
||||
- falha real do debugger;
|
||||
- limitacao do ambiente de execucao;
|
||||
- regressao de CI.
|
||||
|
||||
## Alvo
|
||||
|
||||
- testes de `prometeu-host-desktop-winit` que abrem listener TCP;
|
||||
- fluxo de execucao de testes local e de CI;
|
||||
- documentacao de como rodar a suite completa com requisitos de ambiente.
|
||||
|
||||
## Escopo
|
||||
|
||||
- Identificar os testes realmente dependentes de socket.
|
||||
- Separar esses testes por estrategia clara, por exemplo:
|
||||
- suite dedicada;
|
||||
- `#[ignore]` com comando explicito de execucao;
|
||||
- gate por feature ou por condicao de ambiente;
|
||||
- job dedicado de CI fora de sandbox restritivo.
|
||||
- Preservar cobertura funcional do debugger.
|
||||
- Documentar a forma oficial de rodar esses testes.
|
||||
|
||||
## Fora de Escopo
|
||||
|
||||
- Reescrever o debugger para nao usar TCP.
|
||||
- Redesenhar o protocolo de debug.
|
||||
- Remover testes de integracao do debugger.
|
||||
- Introduzir heuristicas silenciosas que "engulam" falhas reais de rede.
|
||||
|
||||
## Abordagem
|
||||
|
||||
1. Catalogar os testes que fazem bind de porta e verificar se todos sao realmente de integracao.
|
||||
2. Escolher uma estrategia explicita de separacao, preferencialmente uma que mantenha os testes presentes no repo e visiveis na CI.
|
||||
3. Ajustar o comando ou job de CI para executar a suite correta no ambiente correto.
|
||||
4. Documentar localmente como um desenvolvedor deve rodar:
|
||||
- suite padrao;
|
||||
- suite completa com debugger/socket.
|
||||
|
||||
## Criterios de Aceite
|
||||
|
||||
- O fluxo padrao de testes nao produz falso negativo por restricao de socket do ambiente.
|
||||
- Os testes de debugger continuam existindo e continuam sendo executados em algum caminho oficial.
|
||||
- A documentacao deixa claro quando e onde a suite de socket deve rodar.
|
||||
- Falhas reais do debugger continuam visiveis e nao sao mascaradas por skip silencioso sem criterio.
|
||||
|
||||
## Tests
|
||||
|
||||
- Rodar o fluxo padrao de testes no ambiente comum do projeto.
|
||||
- Rodar explicitamente a suite de debugger/socket no ambiente habilitado para bind.
|
||||
- Validar que o job ou comando documentado realmente cobre os testes de reconexao, porta aberta, segunda conexao e resume apos disconnect.
|
||||
|
||||
## Risco
|
||||
|
||||
Medio. O risco principal e esconder regressao real atras de condicionais ambientais mal projetadas. A PR deve tratar ambiente como requisito explicito, nunca como desculpa para reduzir cobertura.
|
||||
@ -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.
|
||||
@ -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.
|
||||
Loading…
x
Reference in New Issue
Block a user