78 lines
3.3 KiB
Markdown
78 lines
3.3 KiB
Markdown
# 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.
|